## Layout(布局基类)
```cpp
class Layout : public UIElement { bool UseCache() const override { return false; } };
```
- 布局容器**一律不缓存**。
## ColumnBox(垂直)/ RowBox(水平)
```cpp
enum class LayoutAlignment { Start, Center, End, Stretch };
enum class Justify { Start, Center, End, SpaceBetween, SpaceAround };
ColumnBox(); RowBox();
void AddChild(std::shared_ptr<UIElement>); void ClearChildren();
void RemoveChild(std::shared_ptr<UIElement>); void RemoveChildAt(int); void InsertChild(int, std::shared_ptr<UIElement>);
void SetSpacing(float);
void SetJustify(Justify); // 主轴:Start/Center/End/SpaceBetween/SpaceAround
void SetCrossAlign(LayoutAlignment); // 交叉轴,默认 Stretch(兼容旧行为)
```
- `ColumnBox` 默认水平填满、垂直不拉伸;`RowBox` 相反。
- `Justify` 只在没有 flex/拉伸子元素时分配剩余空间;`CrossAlign` 设为 Center/Start/End 时按子元素 desiredSize 摆放,不再强制拉满。
###block_red_start
**易错**
- `AddChild` 会 `SetParent(this)`;容器用 `shared_ptr` 拥有子元素。子元素设了显式 `SetHeight` 时,剩余空间按权值**叠加**到该高度上。
###block_red_end
- **`版本`**:`v1.17.0` 起按子元素拉伸权值分配剩余空间。
## GridLayout(网格)
```cpp
using Alignment = LayoutAlignment; // Start / Center / End / Stretch
void AddChild(std::shared_ptr<UIElement>, int row, int col, int rowSpan=1, int colSpan=1,
Alignment hAlign=Alignment::Stretch, Alignment vAlign=Alignment::Stretch);
void SetColumnCount(int); void SetRowCount(int);
void SetSpacing(float h, float v);
void SetColumnStretch(int col, float weight); void SetRowStretch(int row, float weight);
void SetHorizontalAlignment(Alignment); void SetVerticalAlignment(Alignment);
void SetCellAlignment(int row, int col, Alignment h, Alignment v);
```
- 行/列数由 `SetColumnCount/SetRowCount`(或 `SetColumnStretch/SetRowStretch`)定义;**空轨道仍然存在**,不需要占位元素。
- `SetCellAlignment` 控制子元素在自己的 cell 内如何摆放,默认 `Stretch`;`SetHorizontalAlignment/SetVerticalAlignment` 控制整个 Grid 内容在剩余空间中的位置。
- 1×1 Grid 也可以使用内容对齐;`SetColumnStretch(2, ...)` 会建立第 3 列。
- 未显式设行/列拉伸时,单元格轨道权重取**所跨子元素权值的最大者**。
- **`版本`**:`v1.26.0` 起,Grid 自身的显式 `SetWidth/SetHeight` 同时作为 cell 测量范围;不会再出现“对外返回 260、内部按 274+ 排列”的溢出。
## LayoutHost / Card / Page
```cpp
class LayoutHost : public UIElement {
std::shared_ptr<UIElement> GetLayout() const; void SetLayout(...);
std::shared_ptr<UIElement> GetContent() const; void SetContent(...); // 单内容别名
void SetContentAlignment(LayoutAlignment h, LayoutAlignment v); // 默认 Stretch
};
class Card : public LayoutHost { DefaultPadding=12; DefaultCornerRadius=8; ... };
void SetContent(const std::wstring& title, const std::wstring& description, std::shared_ptr<UIElement> action=nullptr);
class Page : public LayoutHost { DefaultPadding=10; ... };
void Page::SetScrollableContent(std::shared_ptr<UIElement> content); // 一行套 ScrollViewer(fill)+8px 边距
```
- `LayoutHost` 是“单内容宿主”;`Card` 是带圆角/描边/悬停的卡片;`Page` 是 `TabView`/`PageHost` 的页面容器。
- `SetContentAlignment(Center, Center)` 可让 Page/Card 的内容整体居中;默认 `Stretch` 保持旧行为。
- 空内容时,`Card/Page` 的显式 `SetWidth/SetHeight` 仍然生效;`ScrollViewer` 无内容时也返回显式/有限视口尺寸。
- `Card::UseCache()` = `HasShadow()`;`Page::UseCache()` = false。
## PageHost(页面宿主 / 过渡)
```cpp
enum class TransitionDirection { Left, Right, Up, Down };
enum class TransitionEasing { Linear, EaseInOut, EaseOut };
void AddPage(std::shared_ptr<Page>); void RemovePage(int); void ClearPages();
void NavigateTo(int index); void SetCurrentIndexInstant(int index);
void SetTransitionDirection(...); void SetTransitionEasing(...); void SetAnimationDuration(float);
int GetCurrentIndex() const; std::shared_ptr<Page> GetCurrentPage() const;
```
- 过渡期间**同时**把源页与目标页作为可见子元素返回;`UpdateAnimation` 每页只更新一次(否则动画速度翻倍)。
###block_red_start
**易错**
- `NavigateTo` 是**异步**的(动画结束才真正切到目标),`GetCurrentPage()`/`GetCurrentIndex()` 在动画期间可能还是旧值。
- 页面内元素显隐请用 `SetVisible()`(会 `InvalidateLayout()`);不要直接改内部可见标志,否则既不会重测也不会重绘。
###block_red_end
- **`版本`**:缓动 `v1.8.1`;**隐藏页缓存延迟释放(约 1.2s,整棵子树递归)** = `v1.18.0`——解决快速切页内存抖动式增长;`MeasureOverride` **测量全部页面** = `v1.23.1`——页面内元素运行时显隐(如选择下拉后显示的 `Expander` 卡片)会立即重新布局并参与命中,不再需要改变窗口尺寸来触发。
## TabView(页签)
见「容器与滚动 / 页签」章。布局系统
Layout、ColumnBox、RowBox、GridLayout、Card、Page、PageHost
Layout(布局基类)
cpp
class Layout : public UIElement { bool UseCache() const override { return false; } };
- 布局容器一律不缓存。
ColumnBox(垂直)/ RowBox(水平)
cpp
enum class LayoutAlignment { Start, Center, End, Stretch };
enum class Justify { Start, Center, End, SpaceBetween, SpaceAround };
ColumnBox(); RowBox();
void AddChild(std::shared_ptr<UIElement>); void ClearChildren();
void RemoveChild(std::shared_ptr<UIElement>); void RemoveChildAt(int); void InsertChild(int, std::shared_ptr<UIElement>);
void SetSpacing(float);
void SetJustify(Justify); // 主轴:Start/Center/End/SpaceBetween/SpaceAround
void SetCrossAlign(LayoutAlignment); // 交叉轴,默认 Stretch(兼容旧行为)
ColumnBox默认水平填满、垂直不拉伸;RowBox相反。Justify只在没有 flex/拉伸子元素时分配剩余空间;CrossAlign设为 Center/Start/End 时按子元素 desiredSize 摆放,不再强制拉满。
易错
AddChild会SetParent(this);容器用shared_ptr拥有子元素。子元素设了显式SetHeight时,剩余空间按权值叠加到该高度上。
版本:v1.17.0起按子元素拉伸权值分配剩余空间。
GridLayout(网格)
cpp
using Alignment = LayoutAlignment; // Start / Center / End / Stretch
void AddChild(std::shared_ptr<UIElement>, int row, int col, int rowSpan=1, int colSpan=1,
Alignment hAlign=Alignment::Stretch, Alignment vAlign=Alignment::Stretch);
void SetColumnCount(int); void SetRowCount(int);
void SetSpacing(float h, float v);
void SetColumnStretch(int col, float weight); void SetRowStretch(int row, float weight);
void SetHorizontalAlignment(Alignment); void SetVerticalAlignment(Alignment);
void SetCellAlignment(int row, int col, Alignment h, Alignment v);
- 行/列数由
SetColumnCount/SetRowCount(或SetColumnStretch/SetRowStretch)定义;空轨道仍然存在,不需要占位元素。 SetCellAlignment控制子元素在自己的 cell 内如何摆放,默认Stretch;SetHorizontalAlignment/SetVerticalAlignment控制整个 Grid 内容在剩余空间中的位置。- 1×1 Grid 也可以使用内容对齐;
SetColumnStretch(2, ...)会建立第 3 列。 - 未显式设行/列拉伸时,单元格轨道权重取所跨子元素权值的最大者。
版本:v1.26.0起,Grid 自身的显式SetWidth/SetHeight同时作为 cell 测量范围;不会再出现“对外返回 260、内部按 274+ 排列”的溢出。
LayoutHost / Card / Page
cpp
class LayoutHost : public UIElement {
std::shared_ptr<UIElement> GetLayout() const; void SetLayout(...);
std::shared_ptr<UIElement> GetContent() const; void SetContent(...); // 单内容别名
void SetContentAlignment(LayoutAlignment h, LayoutAlignment v); // 默认 Stretch
};
class Card : public LayoutHost { DefaultPadding=12; DefaultCornerRadius=8; ... };
void SetContent(const std::wstring& title, const std::wstring& description, std::shared_ptr<UIElement> action=nullptr);
class Page : public LayoutHost { DefaultPadding=10; ... };
void Page::SetScrollableContent(std::shared_ptr<UIElement> content); // 一行套 ScrollViewer(fill)+8px 边距
LayoutHost是“单内容宿主”;Card是带圆角/描边/悬停的卡片;Page是TabView/PageHost的页面容器。SetContentAlignment(Center, Center)可让 Page/Card 的内容整体居中;默认Stretch保持旧行为。- 空内容时,
Card/Page的显式SetWidth/SetHeight仍然生效;ScrollViewer无内容时也返回显式/有限视口尺寸。 Card::UseCache()=HasShadow();Page::UseCache()= false。
PageHost(页面宿主 / 过渡)
cpp
enum class TransitionDirection { Left, Right, Up, Down };
enum class TransitionEasing { Linear, EaseInOut, EaseOut };
void AddPage(std::shared_ptr<Page>); void RemovePage(int); void ClearPages();
void NavigateTo(int index); void SetCurrentIndexInstant(int index);
void SetTransitionDirection(...); void SetTransitionEasing(...); void SetAnimationDuration(float);
int GetCurrentIndex() const; std::shared_ptr<Page> GetCurrentPage() const;
- 过渡期间同时把源页与目标页作为可见子元素返回;
UpdateAnimation每页只更新一次(否则动画速度翻倍)。
易错
NavigateTo是异步的(动画结束才真正切到目标),GetCurrentPage()/GetCurrentIndex()在动画期间可能还是旧值。- 页面内元素显隐请用
SetVisible()(会InvalidateLayout());不要直接改内部可见标志,否则既不会重测也不会重绘。
版本:缓动v1.8.1;隐藏页缓存延迟释放(约 1.2s,整棵子树递归) =v1.18.0——解决快速切页内存抖动式增长;MeasureOverride测量全部页面 =v1.23.1——页面内元素运行时显隐(如选择下拉后显示的Expander卡片)会立即重新布局并参与命中,不再需要改变窗口尺寸来触发。
TabView(页签)
见「容器与滚动 / 页签」章。