ZZufyUI文档首页DocumentationДокументацияDokumentationDocumentationDocumentación

正在准备文档Preparing your docsПодготовка документацииDokumentation wird geladenPréparation de la documentationPreparando la documentación

从这里开始 · 支持全文搜索

框架概览

轻量到几 MB,快到原生合成。 纯头文件、零第三方依赖的 C++20 Windows 自绘 UI 框架,直接构建在 Direct2D 1.1 + DirectComposition 之上。 - 没有 Qt 的打包包袱,没有 Electron 的内存税。 几个头文件,include 即用;应用工程不链

易错点

> 这份文件把散落在代码注释、HANDOFF.md、TODO.md 里的“坑”集中到一处。接手/使用前先扫一遍。 > 优先级:易错 = 违反必踩;注意 = 契约/限制,违反易出问题;约定 = 库的取向;不要 = 明确不做。 --- 1. 链式构造 DSL(ZufyUIDsl.h) | | 状态 |

参考总览

> 本文档覆盖 ZufyUI 框架的全部公开 API,按“使用分类”组织(不是按代码/头文件顺序)。 > 配套阅读:[项目说明与构建](https://github.com/zhc9968/ZufyUI/blob/master/README.md)。 > 阅读方式:本文不是“签名清单”,而是按“它是

约定

颜色与标记 - 红色块:易错——真实踩坑、反直觉行为、会崩溃/UAF/竞争的用法,优先看。 - 橙色块:注意——线程、生命周期、绘制顺序等契约;不一定是错误,但违反后容易出问题。 - 绿色块:推荐——推荐写法、所有权模型、最佳实践。 - 普通项目符号表示普通语义、默认值或版本变化,不代表没有风险。

快速开始

最小程序 cpp include "ZufyUI.h" include "ZufyUIWidgets.h" using namespace ZufyUI; int APIENTRY wWinMain(HINSTANCE, HINSTANCE, LPWSTR, int) { // Windows 子系

基础类型

Color cpp struct Color { float r, g, b, a; // 分量范围 [0,1],不是 0..255 Color(float r=0, float g=0, float b=0, float a=1.0f); static Color FromArgb(uint8t

事件与信号

何时用信号 - 控件对外通知(点击、选中、值变化)用内置 ZSignal。 - 自定义控件对外事件:自己声明 ZSignal 成员并 Fire。 ConnectionThread cpp enum class ConnectionThread { CurrentThread, NewThread,

语言

API 参考 / v1.29.1

容器与滚动

ScrollViewer、ScrollBar、SplitView、Drawer、TabView

下载 Markdown

ScrollViewer

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(独立可复用)

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 起独立复用;ShrunkWidthRatio v1.13.0。

SplitView

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)

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。

易错

  • 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,也不会执行聚焦。
  • 版本:v1.25.0。

TabView

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 化标题 + SetTabLabel v1.13.0;加锁 v1.15.0。
查看源文件docs/src/API.md