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

```cpp
virtual Size MeasureOverride(const Size& avail) = 0;
Size Measure(const Size& avail);      Size GetDesiredSize() const;
virtual void ArrangeOverride(const Rect&);   void Arrange(const Rect&);
Rect GetArrangedRect() const;
void InvalidateLayout();      // 冒泡:向根标脏
void InvalidateLayoutSelf();  // 只标自己(池化/虚拟 rebind 用,不冒泡)
void SetWidth/SetHeight(float);  float GetWidth/GetHeight() const;
void SetFillWidth/SetFillHeight(bool);   bool GetFillWidth/GetFillHeight() const;
void SetMargin(const Thickness&);
void SetMinWidth/SetMinHeight/SetMaxWidth/SetMaxHeight(float);
void SetMinSize/SetMaxSize(float,float);
void SetStretchWeights(float h, float v);
void SetHorizontalStretchWeight(float);   void SetVerticalStretchWeight(float);
virtual float GetDefaultHorizontalStretchWeight() const;   // 同理 Vertical
```
- **拉伸权值**:容器(`ColumnBox`/`RowBox`/`GridLayout`)把**剩余空间**按子元素权值分配。`FillWidth/Height` 等价“该轴权值 1”。`GetDefault*` 是类型默认,`Set*` 覆盖它。

###block_red_start
**易错**

- `SetWidth/SetHeight` 是**固定尺寸**;`SetFillWidth/Height` 是**填满父轴**;两者与拉伸权值叠加,行为要分清。
- `GetDesiredSize()` 是上一次 `Measure` 的结果;未测量过/刚改内容时可能是旧值。
###block_red_end

- **`版本`**:`SetStretchWeights`/`GetDefault*` 自初版存在;**`ColumnBox`/`RowBox`/`GridLayout` 真正按显式权值分配剩余空间 = `v1.17.0`**。

## 绘制 / 子元素 / 裁剪 / 缓存

```cpp
virtual void Draw(ID2D1RenderTarget* rt) = 0;
virtual void RefreshChildren();                       // 更新阶段(UI 线程)重建可见子列表
virtual const std::vector<UIElement*>& GetChildren() const;   // 渲染阶段纯读
virtual bool UseCache() const;   void SetUseCache(bool);      // 默认 true
virtual std::optional<D2D1_RECT_F> GetClipRect() const;
void SetClipRect(const std::optional<Rect>&);
void SetBleed(float);            // 阴影/外发光留边
virtual void ReleaseDeviceResources();        // 只释放自身
void ReleaseDeviceResourcesRecursive();        // 释放整棵子树
virtual D2D1::Matrix3x2F GetChildRenderTransform(UIElement* child) const;
```
- **缓存机制**:`UseCache()==true` 的元素渲染到自身 `ID2D1Bitmap1` 离屏位图;仅当被 `RequestRepaint()` 标记或尺寸变化时重建。出现阴影时自动加 `bleed`。

###block_red_start
**易错**

- **每帧内容在变**(动画、实时文本、旋转)或**实例极多**(上千个)的控件应 `SetUseCache(false)`,否则显存与重建开销爆炸。
- `GetChildren()` 在渲染阶段**必须纯读**;渲染前要保证 `RefreshChildren()` 已调用(窗口在 `AdvanceFrame` 里统一做)。
- `ReleaseDeviceResources()` 只释放自身;释放整棵子树用 `ReleaseDeviceResourcesRecursive()`。
###block_red_end

- **`版本`**:`ReleaseDeviceResourcesRecursive()` = `v1.18.0`(用于隐藏页缓存延迟释放);`SetUseCache(false)` 现在会**立即释放**已有位图。

## 可见性 / 启用 / 提示 / 光标

```cpp
void SetVisible(bool);  void SetVisibleNoInvalidate(bool);  bool IsVisible() const;
void SetEnabled(bool);  bool IsEnabled() const;  bool IsEffectivelyEnabled() const;  // 沿父链
void SetToolTip(const std::wstring&);   virtual std::wstring GetToolTip() const;
void SetCursor(HCURSOR);   HCURSOR GetDesiredCursor() const;
void SetPointerCursors(HCURSOR normal, HCURSOR pressed, HCURSOR disabled);
HCURSOR GetPointerCursor(bool pressed) const;  virtual HCURSOR GetPointerCursorAt(float x, float y, bool pressed) const;
virtual void OnPointerCancel();   // capture stolen/system cancel
```
- 禁用元素不参与命中/悬停。提示会**向上解析**父级提示(如 Button → Label)。

###block_red_start
**易错**

- `SetCursor` 不直接调 `::SetCursor`,而是延迟到 `WM_SETCURSOR`,避免闪烁。
###block_red_end

## 右键菜单 / 拖动区 / 布局参与

```cpp
void SetContextMenu(std::shared_ptr<Menu>);
void SetContextMenuFactory(std::function<std::shared_ptr<Menu>()>);
std::shared_ptr<Menu> BuildContextMenu() const;
enum class LayoutParticipation { Normal, DrawBeforeLayout, DrawAfterLayout };
void SetLayoutParticipation(LayoutParticipation);
void SetDraggable(bool); void SetDragRegion(const Rect&); void ClearDragRegion();
virtual int NonClientHitTest(float x, float y) const;
```

###block_red_start
**易错**

- `DrawBeforeLayout`/`DrawAfterLayout` 由独立通道绘制,**不要再放进根树**,否则画两遍。自定义标题栏就是 `DrawBeforeLayout` 且自己管位置。
###block_red_end

## 事件虚函数与元素信号

```cpp
virtual UIElement* HitTest(float x, float y);
virtual void OnMouseEnter/Leave/Move/Down/Up(...);  virtual bool OnContextMenu(float,float);
virtual void OnKeyDown/Up(WPARAM,LPARAM);  virtual void OnChar(wchar_t);
virtual void OnFocus()/OnBlur();
virtual void UpdateAnimation(float dt);  virtual bool HasActiveAnimation() const;
virtual bool OnMouseWheel(float dx, float dy);
virtual bool IsTextInput() const;  virtual bool AcceptsTab() const;  virtual bool IsFocusable() const;
virtual Rect GetImeCandidateRect() const;  virtual void SetCompositionText(...);
// 元素内置信号
ZSignal<> MouseEnter, MouseLeave, Focused, Blurred;
ZSignal<float,float> MouseMove, MouseDown, MouseUp;
ZSignal<WPARAM,LPARAM> KeyDown, KeyUp;   ZSignal<wchar_t> Char;
```

###block_red_start
**易错**

- 有动画的控件必须让 `HasActiveAnimation()` 正确返回,否则帧循环停了动画就不走。
- 多行编辑器要让 `AcceptsTab()` 返回 true 才会吞掉 Tab 做缩进,否则 Tab 切焦点。
###block_red_end

- **`版本`**:`AcceptsTab()` = `v1.18.0`(配合 `TextEdit`)。

## 无障碍(UIA)— v1.17.0

```cpp
void SetAccessibleName(const std::wstring&);  std::wstring GetAccessibleName() const;
void SetAccessibleDescription(const std::wstring&);
void SetAutomationId(const std::wstring&);     std::wstring GetAutomationIdOrAuto() const;  // 自动 e{n}
void SetAccessibleRole(AccessibleRole);  virtual AccessibleRole GetAccessibleRole() const;
virtual std::wstring DefaultAccessibleName() const;  virtual bool IsAccessibilityIgnored() const;
std::vector<UIElement*> GetAccessibleChildren() const;
// Pattern 虚函数(按角色分派)
virtual void AccessibilityInvoke();
virtual std::wstring GetAccessibleValue() const;  virtual void SetAccessibleValue(const std::wstring&);
virtual bool IsAccessibleReadOnly() const;
virtual int  GetAccessibleToggleState() const;  virtual void AccessibilityToggle();
virtual int  GetAccessibleExpandState() const;  virtual void AccessibilityExpand/Collapse();
virtual double GetAccessibleRangeValue() const; virtual void SetAccessibleRangeValue(double);
virtual double GetAccessibleRangeMin/Max/Step() const;
void AccessibilityNotifyFocus/PropertyChanged/StructureChanged();
```

###block_red_start
**易错**

- 角色决定暴露哪些 UIA Pattern:Button/MenuItem→Invoke;Edit/Document→Value;Slider/ProgressBar→RangeValue;toggle 状态 ≥0→Toggle;expand 状态 ≥0→ExpandCollapse。隐藏节点默认不暴露。
###block_red_end

- **`版本`**:整套 = `v1.17.0`(对应 `Window::SetAccessibilityEnabled`,默认开)。`v1.26.0` 起 UIA provider 缓存/context 生命周期与 COM 回调线程同步,避免 provider 已释放后仍被 UIA 调用。

## 字体(元素级)

```cpp
static void SetGlobalFont(const FontSpec&);  void SetFont(const FontSpec&);
void SetFontFamily/SetFontSize/SetFontWeight(...);  void ClearFont();
virtual std::optional<FontSpec> GetTypeDefaultFont() const;  FontSpec GetEffectiveFontSpec() const;
```
- 解析链:**实例覆盖 → 类型默认 → 全局**。

###block_red_start
**易错**

- 写 `fontOverride_`(含 `std::wstring`)必须与渲染串行;已挂载元素的 `StoreFontOverride`/`InvalidateFontCache` 内部会取 `renderLock_`。
###block_red_end

## 阴影

```cpp
void SetShadow(bool);  bool HasShadow() const;
void SetShadowColor(Color); SetShadowBlur(float); SetShadowOffset(float,float); SetShadowCornerRadius(float);
float GetShadowExtent() const;
```
- 阴影仅对**开启缓存**的元素生效(`Card` 设阴影会自动开缓存)。

## 调试计数(按元素)

`DebugMeasureCount/ArrangeCount/RepaintCount/DrawCount/CacheValid/CacheBytes/MeasureMs/ArrangeMs/DrawMs/AnimationProgress/ResetCounters` 等。
- **`版本`**:`v1.17.0` 加入的逐元素调试计数,配合调试通道 Top-N 使用。
第 6 章

元素基类

UIElement(布局属性、缓存、事件、无障碍、调试)

布局属性

cpp
virtual Size MeasureOverride(const Size& avail) = 0;
Size Measure(const Size& avail);      Size GetDesiredSize() const;
virtual void ArrangeOverride(const Rect&);   void Arrange(const Rect&);
Rect GetArrangedRect() const;
void InvalidateLayout();      // 冒泡:向根标脏
void InvalidateLayoutSelf();  // 只标自己(池化/虚拟 rebind 用,不冒泡)
void SetWidth/SetHeight(float);  float GetWidth/GetHeight() const;
void SetFillWidth/SetFillHeight(bool);   bool GetFillWidth/GetFillHeight() const;
void SetMargin(const Thickness&);
void SetMinWidth/SetMinHeight/SetMaxWidth/SetMaxHeight(float);
void SetMinSize/SetMaxSize(float,float);
void SetStretchWeights(float h, float v);
void SetHorizontalStretchWeight(float);   void SetVerticalStretchWeight(float);
virtual float GetDefaultHorizontalStretchWeight() const;   // 同理 Vertical

易错

  • SetWidth/SetHeight 是固定尺寸;SetFillWidth/Height 是填满父轴;两者与拉伸权值叠加,行为要分清。
  • GetDesiredSize() 是上一次 Measure 的结果;未测量过/刚改内容时可能是旧值。

绘制 / 子元素 / 裁剪 / 缓存

cpp
virtual void Draw(ID2D1RenderTarget* rt) = 0;
virtual void RefreshChildren();                       // 更新阶段(UI 线程)重建可见子列表
virtual const std::vector<UIElement*>& GetChildren() const;   // 渲染阶段纯读
virtual bool UseCache() const;   void SetUseCache(bool);      // 默认 true
virtual std::optional<D2D1_RECT_F> GetClipRect() const;
void SetClipRect(const std::optional<Rect>&);
void SetBleed(float);            // 阴影/外发光留边
virtual void ReleaseDeviceResources();        // 只释放自身
void ReleaseDeviceResourcesRecursive();        // 释放整棵子树
virtual D2D1::Matrix3x2F GetChildRenderTransform(UIElement* child) const;

易错

  • 每帧内容在变(动画、实时文本、旋转)或实例极多(上千个)的控件应 SetUseCache(false),否则显存与重建开销爆炸。
  • GetChildren() 在渲染阶段必须纯读;渲染前要保证 RefreshChildren() 已调用(窗口在 AdvanceFrame 里统一做)。
  • ReleaseDeviceResources() 只释放自身;释放整棵子树用 ReleaseDeviceResourcesRecursive()。

可见性 / 启用 / 提示 / 光标

cpp
void SetVisible(bool);  void SetVisibleNoInvalidate(bool);  bool IsVisible() const;
void SetEnabled(bool);  bool IsEnabled() const;  bool IsEffectivelyEnabled() const;  // 沿父链
void SetToolTip(const std::wstring&);   virtual std::wstring GetToolTip() const;
void SetCursor(HCURSOR);   HCURSOR GetDesiredCursor() const;
void SetPointerCursors(HCURSOR normal, HCURSOR pressed, HCURSOR disabled);
HCURSOR GetPointerCursor(bool pressed) const;  virtual HCURSOR GetPointerCursorAt(float x, float y, bool pressed) const;
virtual void OnPointerCancel();   // capture stolen/system cancel

易错

  • SetCursor 不直接调 ::SetCursor,而是延迟到 WM_SETCURSOR,避免闪烁。

右键菜单 / 拖动区 / 布局参与

cpp
void SetContextMenu(std::shared_ptr<Menu>);
void SetContextMenuFactory(std::function<std::shared_ptr<Menu>()>);
std::shared_ptr<Menu> BuildContextMenu() const;
enum class LayoutParticipation { Normal, DrawBeforeLayout, DrawAfterLayout };
void SetLayoutParticipation(LayoutParticipation);
void SetDraggable(bool); void SetDragRegion(const Rect&); void ClearDragRegion();
virtual int NonClientHitTest(float x, float y) const;

易错

  • DrawBeforeLayout/DrawAfterLayout 由独立通道绘制,不要再放进根树,否则画两遍。自定义标题栏就是 DrawBeforeLayout 且自己管位置。

事件虚函数与元素信号

cpp
virtual UIElement* HitTest(float x, float y);
virtual void OnMouseEnter/Leave/Move/Down/Up(...);  virtual bool OnContextMenu(float,float);
virtual void OnKeyDown/Up(WPARAM,LPARAM);  virtual void OnChar(wchar_t);
virtual void OnFocus()/OnBlur();
virtual void UpdateAnimation(float dt);  virtual bool HasActiveAnimation() const;
virtual bool OnMouseWheel(float dx, float dy);
virtual bool IsTextInput() const;  virtual bool AcceptsTab() const;  virtual bool IsFocusable() const;
virtual Rect GetImeCandidateRect() const;  virtual void SetCompositionText(...);
// 元素内置信号
ZSignal<> MouseEnter, MouseLeave, Focused, Blurred;
ZSignal<float,float> MouseMove, MouseDown, MouseUp;
ZSignal<WPARAM,LPARAM> KeyDown, KeyUp;   ZSignal<wchar_t> Char;

易错

  • 有动画的控件必须让 HasActiveAnimation() 正确返回,否则帧循环停了动画就不走。
  • 多行编辑器要让 AcceptsTab() 返回 true 才会吞掉 Tab 做缩进,否则 Tab 切焦点。

无障碍(UIA)— v1.17.0

cpp
void SetAccessibleName(const std::wstring&);  std::wstring GetAccessibleName() const;
void SetAccessibleDescription(const std::wstring&);
void SetAutomationId(const std::wstring&);     std::wstring GetAutomationIdOrAuto() const;  // 自动 e{n}
void SetAccessibleRole(AccessibleRole);  virtual AccessibleRole GetAccessibleRole() const;
virtual std::wstring DefaultAccessibleName() const;  virtual bool IsAccessibilityIgnored() const;
std::vector<UIElement*> GetAccessibleChildren() const;
// Pattern 虚函数(按角色分派)
virtual void AccessibilityInvoke();
virtual std::wstring GetAccessibleValue() const;  virtual void SetAccessibleValue(const std::wstring&);
virtual bool IsAccessibleReadOnly() const;
virtual int  GetAccessibleToggleState() const;  virtual void AccessibilityToggle();
virtual int  GetAccessibleExpandState() const;  virtual void AccessibilityExpand/Collapse();
virtual double GetAccessibleRangeValue() const; virtual void SetAccessibleRangeValue(double);
virtual double GetAccessibleRangeMin/Max/Step() const;
void AccessibilityNotifyFocus/PropertyChanged/StructureChanged();

易错

  • 角色决定暴露哪些 UIA Pattern:Button/MenuItem→Invoke;Edit/Document→Value;Slider/ProgressBar→RangeValue;toggle 状态 ≥0→Toggle;expand 状态 ≥0→ExpandCollapse。隐藏节点默认不暴露。

字体(元素级)

cpp
static void SetGlobalFont(const FontSpec&);  void SetFont(const FontSpec&);
void SetFontFamily/SetFontSize/SetFontWeight(...);  void ClearFont();
virtual std::optional<FontSpec> GetTypeDefaultFont() const;  FontSpec GetEffectiveFontSpec() const;

易错

  • 写 fontOverride_(含 std::wstring)必须与渲染串行;已挂载元素的 StoreFontOverride/InvalidateFontCache 内部会取 renderLock_。

阴影

cpp
void SetShadow(bool);  bool HasShadow() const;
void SetShadowColor(Color); SetShadowBlur(float); SetShadowOffset(float,float); SetShadowCornerRadius(float);
float GetShadowExtent() const;

调试计数(按元素)

DebugMeasureCount/ArrangeCount/RepaintCount/DrawCount/CacheValid/CacheBytes/MeasureMs/ArrangeMs/DrawMs/AnimationProgress/ResetCounters 等。 - 版本:v1.17.0 加入的逐元素调试计数,配合调试通道 Top-N 使用。

↑