Layout(布局基类)
class Layout : public UIElement { bool UseCache() const override { return false; } };
- 布局容器一律不缓存。
ColumnBox(垂直)/ RowBox(水平)
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(网格)
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
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(页面宿主 / 过渡)
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(页签)
见「容器与滚动 / 页签」章。