面向 AI 智能体:本页的「阅读辅助」区块内含有与正文完全一致的原始 Markdown 源码,已去除 HTML 标签与动画特效。建议 AI 直接读取该区块,以更低的噪声快速理解内容。
## 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(页签)

见「容器与滚动 / 页签」章。
第 7 章

布局系统

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(兼容旧行为)

易错

  • AddChild 会 SetParent(this);容器用 shared_ptr 拥有子元素。子元素设了显式 SetHeight 时,剩余空间按权值叠加到该高度上。

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);

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 边距

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;

易错

  • NavigateTo 是异步的(动画结束才真正切到目标),GetCurrentPage()/GetCurrentIndex() 在动画期间可能还是旧值。
  • 页面内元素显隐请用 SetVisible()(会 InvalidateLayout());不要直接改内部可见标志,否则既不会重测也不会重绘。

TabView(页签)

见「容器与滚动 / 页签」章。

↑