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,

语言

维护与参考 / v1.29.1

开发原则

下载 Markdown

协作流程规则(必须遵守)

  • 提交/推送前必须先经用户同意:不要自动 git commit / git push(含 Gitee/GitHub/gh-pages),等到用户明确说“提交/推送”再执行。
  • 不要自动更新文档:API 文档、README、更新日志等,只有用户明确指定时才更新;不要顺手自动改。
  • 每次提交信息要如实描述本次改动。

Bug 处理原则(最高优先级)

遇到任何 bug(无论轻重缓急),先定位根源,再从根源修复:

  1. 绝不允许用“新机制”让 bug 无法触发,来掩盖问题(那是掩盖,不是修复)。
  2. 如果根源确实在外部(Windows API / 系统 / 第三方库),才考虑绕过它,并在文档中明确标注“这是对外部问题的规避”。
  3. 如果根源在本项目内部代码,必须找到它并从根源修复。
  4. 如果找不到根源:如实说明“找不到,未定位”,交由用户(或用户的其他分析)定位;找到后再修复。绝不猜测、绝不用“最可疑”下结论、绝不靠引入机制来掩盖。

布局 / UIA / 动画事故教训(必须遵守)

  • 显式尺寸是契约:GridLayout 的 width_/height_ 必须进入测量范围,不能“返回 260、内部按 274 排”。禁止用裁剪掩盖排布溢出;先修测量契约。
  • UIA provider 是多线程边界:UIA 方法可能从 COM/RPC 线程进入,UiaContexts、elements、provider 的 elem_/ctx_ 不能无锁读写。缓存必须持有明确生命周期;context 不能在 UIA 仍可能持有 provider 时被 erase/析构;provider 内不要保存会失效的裸 context/元素指针。
  • 动画不要写用户尺寸属性:不要在 UpdateAnimation 每帧 SetHeight/重复 InvalidateLayout。用独立动画状态驱动测量,每帧最多一次布局失效;内容显隐要同步 childrenDirty_。
  • 展开容器不能只看动画进度决定子元素是否入列:expanded_ == true 时内容必须进入 childrenView_,不能只靠 expandProg_ > 0;否则首次展开后动画起点为 0,childrenDirty_ 不再变化,折叠再展开会永久不显示内容。
  • 初始折叠也要测量一次内容:否则内容子树从未 Measure,首次展开可能沿用未初始化/旧尺寸,出现文字偏右、下拉框被裁剪,直到窗口 resize 才恢复。
  • 崩溃码要读对:c0000409 只是“安全检测失败”的总码;Subcode 0xA = FAST_FAIL_GUARD_ICALL_CHECK_FAILURE(CFG 间接调用校验失败),不是 Stack Cookie,也不是 TDR。必须用 minidump 的 !analyze/k 定位,不能凭 WER 主码猜。
  • 可访问性对象生命周期:Release/ForgetAccessibleElement/窗口关闭必须与 UIA 回调串行化;不得留下仍可被 UIA 调用的已释放对象或悬垂 context。
  • 新增并发/动画/UIA 相关修复必须附回归测试或可复现验证;没有证据时按“未定位”处理,不要用 try/catch、延时或限幅掩盖。
  • 自定义边框 / DWM frame:Win10 不要设置 DWMWA_WINDOW_CORNER_PREFERENCE、不要用 SetWindowRgn 裁圆角;Win10/Win11 自定义边框都保留 DwmExtendFrameIntoClientArea({1,1,1,1}),并在 WM_SIZE / WM_WINDOWPOSCHANGED / 背景重载后重新挂 frame 状态,否则 Snap 会丢边框/阴影。圆角只由 Win11 DWM 处理。
  • 公开圆角 API 已删除:WindowCorner/SetWindowCorner/GetWindowCorner/DSL corner() 不再提供;需要自定义圆角的用户自行调用 Win32 DWM API,并承担 Win10/Snap 边框阴影风险。
  • 渲染驱动是进程级开关:SetRenderDriver 必须在第一次 Window::Create/D3D 设备创建之前调用;WARP 只改变应用自己的 D3D11/D2D 内容渲染,不保证 DWM/Compositor 不用 GPU,不能把“省内存”宣传成“零 GPU”。

依赖与约束(避免埋雷)

  • UIElement::GetChildren() 返回的是元素内部缓冲的引用,其有效期为“该元素的子列表或可视状态发生变化 / 再次调用该元素的 GetChildren() 之前”。遍历期间不得对同一个元素再次调用 GetChildren()(容器递归自己子元素时用的是各自独立的缓冲,安全)。
  • 元素内部用窗口 id(不是裸指针)记录所属窗口;窗口销毁后 GetWindow() 返回 nullptr。
  • UIElement / Window 继承 ConnectionOwner,Connect(signal, slot) 返回 Connection;连接登记在接收者 ConnectionGroup,随接收者析构自动断开。成员函数指针用自由 Connect(receiver, signal, &Class::Method) 或 ConnectWeak,不要写 elem->Connect(sig, &Class::Method)。
  • 所有与窗口相关的全局信号(UIZSignals::*)都携带 Window*;订阅者必须用 GetWindow() 过滤,禁止跨窗口处理。
  • 数据视图(List/Table/Tree)的按项/按行元数据要么绑定到项目对象、要么在排序/增删时重映射,禁止用会失效的下标或裸指针悬挂。

链式构造 / API 约定(保持调用侧一致,别让用户猜)

  • .with(&T::Method, args...):只用于无默认参数、无重载、非初始化列表的成员函数。
    • 带默认参数的成员函数,成员指针含全部形参 → .with(&X::F, a) 报“参数太少”。不要再往库里加这种函数;新函数若需要可选行为,拆成两个无默认参数的重载(如 SetCheckable(bool) + SetCheckableShallow(bool))。
    • 需要显式给非默认值时用拆分后的具名重载(如 ...Recursive / ...Selected / ...Radio / ...Full / ...Impl)。
  • .apply([](T& x){ ... }):逃生舱 —— 仅用于初始化列表、重载歧义、或多步条件逻辑。不要当主写法。
  • ->SetXxx(...):在 DSL 链中尽量不用;需要时用 .with;确实不行才 ->。
  • DSL 短工厂统一 Z 前缀:ZLbl / ZBtn / ZSlider / ZCard / ZPage / ZMenu …;因此同时 using namespace ZufyUI; using namespace ZufyUI::dsl; 也不会再和类名冲突。
  • 主题钩子:ThemeManager::RegisterHook/RegisterSubtreeApplier 返回 RAII HookHandle(析构自动断开);想长期有效就持有它;库内部固定钩子用 RegisterHookPermanent。
  • 整页滚动:page->SetScrollableContent(content) 一行搞定(别再手写 GridLayout + ScrollViewer 样板)。
  • 更完整的易错点集中在 docs/pitfalls.md(改库前先扫一遍)。

双语文档规则(API.md / API.en.md)

  • 两版同一章节的代码块必须逐行对齐:行数相同、顺序相同(函数签名集合也自然一致)。叙述、注释、示例的文字可以各自不同,但代码块的行数与顺序必须一致——行数不匹配 = 一定有一边漏了。
  • 改动任一版后运行校验(退出码 0 = 一致):
    python tools/check_api_parity.py
    
    脚本校验“每章代码块的方法名集合 + 非空行数”;任一项不一致即报错。
  • 文档(.md / .tex)保存为 UTF-8 无 BOM;C++ 源文件(.h/.cpp)保存为 UTF-8 带 BOM(中文宽字面量需要)。需要无 BOM / 纯 ASCII 副本时,用 tools/export_ascii.py 生成 dist/ascii(不提交)。

构建

powershell -ExecutionPolicy Bypass -File tools/build.ps1
  • 脚本通过 vswhere 自动探测 Visual Studio / MSBuild,不写死安装路径;构建前会杀掉占用进程。
  • 可选:-Configuration Debug、-Platform x86、-SkipDebugger、-SkipTests、-VsRoot <path>。
  • 纯 ASCII 分发副本:python tools/export_ascii.py(输出到 dist/ascii,见生成目录的 README.md)。
  • 文档站点:python tools/build_docs.py(ZufyUI 包装;通用转换器在 ../md2html,不要把库专用逻辑写进它)。
查看源文件AGENTS.md