## 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`。容器与滚动
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仍允许程序化/滚轮滚动(只是不显示条)。
版本: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预留槽位。
易错
ValueChanged是std::function(不是ZSignal),签名(float, bool)。ShrinkTarget的“空闲等待缩小”倒计时不再算作活跃动画——否则会把整窗顶进动画模式导致数据重绘不落屏。代价:空闲缩小变惰性(到点后由下一帧触发)。
版本:v1.11.0起独立复用;ShrunkWidthRatiov1.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都放不下时,展开按钮仍然显示,但会变灰、不可悬停也不可点击;空间恢复后自动重新启用。
易错
Orientation命名反直觉(Vertical指竖直分隔条、水平排列两栏)。- 覆盖层与本控件内部的
Overlay子元素有关——它是最后一个子元素(框架按子元素顺序绘制),所以天生画在两栏内容之上;不要试图在SplitView::Draw里画这类装饰(会被内容盖住)。
版本: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;
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(根布局或某个GridLayoutcell),不覆盖窗口标题栏/菜单栏;要压暗整个内容区就放在对应区域的最外层。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,也不会执行聚焦。
版本: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);
易错
- 内容由内部
PageHost承载;AddTab首个页签会自动选中并触发SelectionChanged。 SetSelectedIndex/切换是异步的(过渡动画结束才定),GetSelectedContent()/索引在动画期间可能仍是旧值。
版本:v1.11.0;Label 化标题 +SetTabLabelv1.13.0;加锁v1.15.0。