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

```cpp
enum class ScrollBarVisibility { Auto, Always, Hidden };
ZSignal<float,float> ScrollChanged;   // (offsetX, offsetY),动画中也发
void SetContent(std::shared_ptr<UIElement>);
void SetVertical/HorizontalScrollEnabled(bool);
void SetVertical/HorizontalScrollBarVisibility(ScrollBarVisibility);
void SetScrollBarWidth(float);  void SetScrollWheelStep(float);  void SetAnimationSpeed(float);
void ScrollTo(float x,float y,bool animated=true);  void ScrollBy(...);
float GetScrollOffsetX/Y() const;
```

###block_red_start
**易错**

- `Hidden` 仍允许程序化/滚轮滚动(只是不显示条)。
###block_red_end

- **`版本`**:`v1.18.0` 起 `ScrollViewer::UseCache()==false`(内容常变/可滚动,缓存无益且占大位图)。

## ScrollBar(独立可复用)

```cpp
std::function<void(float value, bool animate)> ValueChanged;
explicit ScrollBar(bool vertical);
void SetRange(float value, float maxValue, float viewportSize);   // 宿主每帧推入
void SetBarWidth(float);  void SetMinLength(float);  void SetHitExtra(float);
void SetColors(D2D1_COLOR_F thumb, D2D1_COLOR_F hoverThumb, D2D1_COLOR_F track);
void SetIdleDelay(float);  void SetAutoShrink(bool);  void MarkActive();
inline static float ShrunkWidthRatio;   // 默认 0.30
```
- 拖动 → `animate=false`(跟手);点轨道 → `animate=true`。悬停扩张 + 空闲缩小;宿主用 `ShrunkWidthRatio` 预留槽位。

###block_red_start
**易错**

- `ValueChanged` 是 `std::function`(不是 `ZSignal`),签名 `(float, bool)`。
- `ShrinkTarget` 的“空闲等待缩小”倒计时**不再**算作活跃动画——否则会把整窗顶进动画模式导致数据重绘不落屏。代价:空闲缩小变**惰性**(到点后由下一帧触发)。
###block_red_end

- **`版本`**:`v1.11.0` 起独立复用;`ShrunkWidthRatio` `v1.13.0`。

## SplitView

```cpp
enum class Orientation { Vertical, Horizontal };   // Vertical = 左右两栏 + 竖直分隔条
ZSignal<float> SplitChanged;   // 新比例 0..1
void SetFirst/SetSecond(std::shared_ptr<UIElement>);
void SetSplitRatio(float);  void SetSplitterWidth(float);  void SetMinFirst/MinSecond(float);
void SetInsufficientSpaceDefaultSide(int);  int GetInsufficientSpaceDefaultSide() const;
void SetAutoCollapseOnInsufficientSpace(bool);  bool GetAutoCollapseOnInsufficientSpace() const;
ZSignal<int> CollapsedChanged;   // 0=未折叠 1=第一栏 2=第二栏
void SetCollapseEnabled(bool);   bool IsCollapseEnabled() const;   void SetCollapseThreshold(float);
void CollapseFirst/CollapseSecond();   void Expand();   bool IsFirstCollapsed/IsSecondCollapsed() const;
void SetExpandButtonColors(Color,Color,Color);   void SetExpandButtonSize(float w,float h);
void SwitchToFirst/SwitchToSecond(bool animate = true);  void SwitchToPane(int side, bool animate = true);
void SetSwitchAnimationDuration(float);  void SetSwitchAnimationEasing(Easing);
bool IsSwitching() const;  float GetSwitchProgress() const;  int GetActivePane() const;
ZSignal<int> ActivePaneChanged;   // 1=first, 2=second
bool UseCache() const override { return false; }
```
- **折叠(`v1.21.0`)**:把分隔条拖到**距某侧边缘 `CollapseThreshold`(默认 28px)内** → 该侧内容**上方**浮出半透明强调色覆盖层 + 指向折叠方向的箭头(alpha 渐入渐出);**此时不改内容**,**松手**才真正折叠(该侧尺寸带缓动从当前值变为 0)。折叠后该侧边缘出现小按钮(圆角浅灰 + 指向展开方向的箭头 + 悬停缓动),点击后该侧尺寸带缓动从 0 变为**最小极限值**(`SetMinFirst/MinSecond`;未设则回到折叠前比例)。整个功能可 `SetCollapseEnabled(false)` 关闭。
- **全屏面板切换(v1.28.0)**:`SwitchToFirst/Second` 从一个完整面板滑动过渡到另一个完整面板(类似 PageHost),不依赖两面板同时容得下;方向/时长/缓动可配置,结束后更新折叠状态并发出 `ActivePaneChanged`。
- 当剩余空间连 `minFirst + minSecond` 都放不下时,展开按钮仍然显示,但会变灰、不可悬停也不可点击;空间恢复后自动重新启用。

###block_red_start
**易错**

- `Orientation` 命名反直觉(`Vertical` 指竖直分隔条、水平排列两栏)。
- 覆盖层与本控件内部的 `Overlay` 子元素有关——它是**最后一个子元素**(框架按子元素顺序绘制),所以天生画在两栏内容**之上**;不要试图在 `SplitView::Draw` 里画这类装饰(会被内容盖住)。
###block_red_end

- **`版本`**:`v1.12.0`;NaN/Inf 守卫 `v1.14.0`;折叠/小按钮 `v1.21.0`。

## Drawer(v1.25.0)

```cpp
enum class DrawerSide { Left, Right, Top, Bottom };
enum class DrawerMode { Overlay, Push, Permanent };
ZSignal<bool> OpenChanged;  ZSignal<> Opened, Closed, ScrimClicked;
void SetContent/SetPanel(std::shared_ptr<UIElement>);
void SetSide(DrawerSide);  void SetMode(DrawerMode);  void SetPanelSize(float);
void SetPanelPadding(const Thickness&);  void SetPanelCornerRadius(float);
void SetPanelBackgroundColor(Color);  void SetPanelBorderColor(Color);
void SetPanelShadow(bool);  void SetPanelShadowColor(Color);
void SetContentBorder(bool);  void SetContentBorderColor(Color);  void SetContentBorderCornerRadius(float);
void SetScrimColor(Color);  void SetScrimOpacity(float);  void SetModal(bool);
void SetDismissOnScrimClick(bool);  void SetDismissOnEscape(bool);
void SetFocusOnOpen(std::shared_ptr<UIElement>);
void SetAnimationDuration(float);  void SetAnimationEasing(Easing);
void Open/Close/Toggle();  bool IsOpen/IsAnimating() const;  float GetOpenProgress() const;
```
###block_list_start
###block_item_start
**Overlay**

圆角遮罩覆盖内容;点外部或 Esc 关闭。适合导航、筛选等临时面板。
###block_item_end
###block_item_start
**Push**

打开时内容让位,面板参与布局;适合需要同时查看列表和详情的场景。
###block_item_end
###block_item_start
**Permanent**

常驻侧栏,无动画/遮罩,`Close` 无效;适合固定导航或设置入口。
###block_item_end
###block_list_end

###block_green_start
**推荐**

优先把 `Drawer` 当根布局或放进 `GridLayout` 的 cell;普通内容放 Overlay,需要内容缩窄时用 Push,长期导航用 Permanent。面板内容用 `SetPanel`,主内容用 `SetContent`。
###block_green_end

###block_orange_start

###block_red_start
**易错**

- `SetContent` 是主内容(会被抽屉遮住/让位),`SetPanel` 才是抽屉面板。把面板内容塞进 `SetContent` 不会得到面板背景、内边距、圆角和阴影。
- `SetPanelSize` 是面板**外框**尺寸;默认 16px 内边距会先从面板内容中扣除(例如 `200` 的外宽只剩 `168` 给内容)。面板内容需要更宽时,调大 `SetPanelSize` 或减小 `SetPanelPadding`。
- `Drawer` 是布局控件,只覆盖它自己的 arranged rect(根布局或某个 `GridLayout` cell),**不覆盖**窗口标题栏/菜单栏;要压暗整个内容区就放在对应区域的最外层。
- `Open()` 立即把目标状态设为打开并触发 `OpenChanged`;`Opened`/`Closed` 要等动画结束才触发。`IsOpen()` 返回目标状态,不是当前进度;动画中请用 `IsAnimating()` / `GetOpenProgress()`。
- `Permanent` 模式会强制打开、进度直接为 1、无动画/遮罩;`Close()` / `SetOpen(false)` 被忽略。从 Permanent 切回 Overlay/Push **不会自动关闭**,需要再调 `Close()`。
- Scrim 只在 Overlay 模式存在;`SetDismissOnScrimClick` / `ScrimClicked` 只在 `SetModal(true)` 且进度 > 0 时生效。`SetModal(false)` 后点击会落到内容上,`ScrimClicked` 不会触发。
- `SetScrimOpacity(0)` 只是把遮罩画成透明,模态命中仍在(仍拦截点击);要穿透请用 `SetModal(false)`。
- `SetContentBorder` 只在 Overlay 模式绘制;Push/Permanent 没有内容边框。`SetPanelShadow` 的内层会被不透明面板背景覆盖,只有外侧阴影可见,边框最后绘制。
- Esc 拦截和 `SetFocusOnOpen` 都要求 `Drawer` 已挂到 `Window`;还没 attach 时不会注册 Esc,也不会执行聚焦。
###block_red_end

- **`版本`**:`v1.25.0`。

## TabView

```cpp
struct Tab { std::shared_ptr<Label> label; std::shared_ptr<Page> page; bool closable; ... };
ZSignal<int> SelectionChanged;   ZSignal<int> TabCloseRequested;
int  AddTab(const std::wstring&, std::shared_ptr<UIElement> content=nullptr, bool closable=false, int id=-1);
int  AddTab(std::shared_ptr<Label>, ...);  int FindTabById(int) const;  int GetTabId(int) const;  bool RemoveTabById(int);
void InsertTab(int, ...);  void RemoveTab(int);  void ClearTabs();
void SetTabTitle(int, ...);  void SetTabLabel(int, std::shared_ptr<Label>);  void SetTabContent(int, ...);
void SetSelectedIndex(int);  int GetSelectedIndex() const;
void SetTransitionDirection(PageHost::TransitionDirection);  void SetAutoTransitionDirection(bool);
```

###block_red_start
**易错**

- 内容由内部 `PageHost` 承载;`AddTab` 首个页签会自动选中并触发 `SelectionChanged`。
- `SetSelectedIndex`/切换是**异步**的(过渡动画结束才定),`GetSelectedContent()`/索引在动画期间可能仍是旧值。
###block_red_end

- **`版本`**:`v1.11.0`;Label 化标题 + `SetTabLabel` `v1.13.0`;加锁 `v1.15.0`。
第 12 章

容器与滚动

ScrollViewer、ScrollBar、SplitView、Drawer、TabView

ScrollViewer

cpp
enum class ScrollBarVisibility { Auto, Always, Hidden };
ZSignal<float,float> ScrollChanged;   // (offsetX, offsetY),动画中也发
void SetContent(std::shared_ptr<UIElement>);
void SetVertical/HorizontalScrollEnabled(bool);
void SetVertical/HorizontalScrollBarVisibility(ScrollBarVisibility);
void SetScrollBarWidth(float);  void SetScrollWheelStep(float);  void SetAnimationSpeed(float);
void ScrollTo(float x,float y,bool animated=true);  void ScrollBy(...);
float GetScrollOffsetX/Y() const;

易错

  • Hidden 仍允许程序化/滚轮滚动(只是不显示条)。

ScrollBar(独立可复用)

cpp
std::function<void(float value, bool animate)> ValueChanged;
explicit ScrollBar(bool vertical);
void SetRange(float value, float maxValue, float viewportSize);   // 宿主每帧推入
void SetBarWidth(float);  void SetMinLength(float);  void SetHitExtra(float);
void SetColors(D2D1_COLOR_F thumb, D2D1_COLOR_F hoverThumb, D2D1_COLOR_F track);
void SetIdleDelay(float);  void SetAutoShrink(bool);  void MarkActive();
inline static float ShrunkWidthRatio;   // 默认 0.30

易错

  • ValueChanged 是 std::function(不是 ZSignal),签名 (float, bool)。
  • ShrinkTarget 的“空闲等待缩小”倒计时不再算作活跃动画——否则会把整窗顶进动画模式导致数据重绘不落屏。代价:空闲缩小变惰性(到点后由下一帧触发)。

SplitView

cpp
enum class Orientation { Vertical, Horizontal };   // Vertical = 左右两栏 + 竖直分隔条
ZSignal<float> SplitChanged;   // 新比例 0..1
void SetFirst/SetSecond(std::shared_ptr<UIElement>);
void SetSplitRatio(float);  void SetSplitterWidth(float);  void SetMinFirst/MinSecond(float);
void SetInsufficientSpaceDefaultSide(int);  int GetInsufficientSpaceDefaultSide() const;
void SetAutoCollapseOnInsufficientSpace(bool);  bool GetAutoCollapseOnInsufficientSpace() const;
ZSignal<int> CollapsedChanged;   // 0=未折叠 1=第一栏 2=第二栏
void SetCollapseEnabled(bool);   bool IsCollapseEnabled() const;   void SetCollapseThreshold(float);
void CollapseFirst/CollapseSecond();   void Expand();   bool IsFirstCollapsed/IsSecondCollapsed() const;
void SetExpandButtonColors(Color,Color,Color);   void SetExpandButtonSize(float w,float h);
void SwitchToFirst/SwitchToSecond(bool animate = true);  void SwitchToPane(int side, bool animate = true);
void SetSwitchAnimationDuration(float);  void SetSwitchAnimationEasing(Easing);
bool IsSwitching() const;  float GetSwitchProgress() const;  int GetActivePane() const;
ZSignal<int> ActivePaneChanged;   // 1=first, 2=second
bool UseCache() const override { return false; }

易错

  • Orientation 命名反直觉(Vertical 指竖直分隔条、水平排列两栏)。
  • 覆盖层与本控件内部的 Overlay 子元素有关——它是最后一个子元素(框架按子元素顺序绘制),所以天生画在两栏内容之上;不要试图在 SplitView::Draw 里画这类装饰(会被内容盖住)。

Drawer(v1.25.0)

cpp
enum class DrawerSide { Left, Right, Top, Bottom };
enum class DrawerMode { Overlay, Push, Permanent };
ZSignal<bool> OpenChanged;  ZSignal<> Opened, Closed, ScrimClicked;
void SetContent/SetPanel(std::shared_ptr<UIElement>);
void SetSide(DrawerSide);  void SetMode(DrawerMode);  void SetPanelSize(float);
void SetPanelPadding(const Thickness&);  void SetPanelCornerRadius(float);
void SetPanelBackgroundColor(Color);  void SetPanelBorderColor(Color);
void SetPanelShadow(bool);  void SetPanelShadowColor(Color);
void SetContentBorder(bool);  void SetContentBorderColor(Color);  void SetContentBorderCornerRadius(float);
void SetScrimColor(Color);  void SetScrimOpacity(float);  void SetModal(bool);
void SetDismissOnScrimClick(bool);  void SetDismissOnEscape(bool);
void SetFocusOnOpen(std::shared_ptr<UIElement>);
void SetAnimationDuration(float);  void SetAnimationEasing(Easing);
void Open/Close/Toggle();  bool IsOpen/IsAnimating() const;  float GetOpenProgress() const;

Overlay

圆角遮罩覆盖内容;点外部或 Esc 关闭。适合导航、筛选等临时面板。

Push

打开时内容让位,面板参与布局;适合需要同时查看列表和详情的场景。

Permanent

常驻侧栏,无动画/遮罩,Close 无效;适合固定导航或设置入口。

推荐

优先把 Drawer 当根布局或放进 GridLayout 的 cell;普通内容放 Overlay,需要内容缩窄时用 Push,长期导航用 Permanent。面板内容用 SetPanel,主内容用 SetContent。

block_orange_start

易错

  • SetContent 是主内容(会被抽屉遮住/让位),SetPanel 才是抽屉面板。把面板内容塞进 SetContent 不会得到面板背景、内边距、圆角和阴影。
  • SetPanelSize 是面板外框尺寸;默认 16px 内边距会先从面板内容中扣除(例如 200 的外宽只剩 168 给内容)。面板内容需要更宽时,调大 SetPanelSize 或减小 SetPanelPadding。
  • Drawer 是布局控件,只覆盖它自己的 arranged rect(根布局或某个 GridLayout cell),不覆盖窗口标题栏/菜单栏;要压暗整个内容区就放在对应区域的最外层。
  • Open() 立即把目标状态设为打开并触发 OpenChanged;Opened/Closed 要等动画结束才触发。IsOpen() 返回目标状态,不是当前进度;动画中请用 IsAnimating() / GetOpenProgress()。
  • Permanent 模式会强制打开、进度直接为 1、无动画/遮罩;Close() / SetOpen(false) 被忽略。从 Permanent 切回 Overlay/Push 不会自动关闭,需要再调 Close()。
  • Scrim 只在 Overlay 模式存在;SetDismissOnScrimClick / ScrimClicked 只在 SetModal(true) 且进度 > 0 时生效。SetModal(false) 后点击会落到内容上,ScrimClicked 不会触发。
  • SetScrimOpacity(0) 只是把遮罩画成透明,模态命中仍在(仍拦截点击);要穿透请用 SetModal(false)。
  • SetContentBorder 只在 Overlay 模式绘制;Push/Permanent 没有内容边框。SetPanelShadow 的内层会被不透明面板背景覆盖,只有外侧阴影可见,边框最后绘制。
  • Esc 拦截和 SetFocusOnOpen 都要求 Drawer 已挂到 Window;还没 attach 时不会注册 Esc,也不会执行聚焦。

TabView

cpp
struct Tab { std::shared_ptr<Label> label; std::shared_ptr<Page> page; bool closable; ... };
ZSignal<int> SelectionChanged;   ZSignal<int> TabCloseRequested;
int  AddTab(const std::wstring&, std::shared_ptr<UIElement> content=nullptr, bool closable=false, int id=-1);
int  AddTab(std::shared_ptr<Label>, ...);  int FindTabById(int) const;  int GetTabId(int) const;  bool RemoveTabById(int);
void InsertTab(int, ...);  void RemoveTab(int);  void ClearTabs();
void SetTabTitle(int, ...);  void SetTabLabel(int, std::shared_ptr<Label>);  void SetTabContent(int, ...);
void SetSelectedIndex(int);  int GetSelectedIndex() const;
void SetTransitionDirection(PageHost::TransitionDirection);  void SetAutoTransitionDirection(bool);

易错

  • 内容由内部 PageHost 承载;AddTab 首个页签会自动选中并触发 SelectionChanged。
  • SetSelectedIndex/切换是异步的(过渡动画结束才定),GetSelectedContent()/索引在动画期间可能仍是旧值。
↑