协作流程规则(必须遵守)
- 提交/推送前必须先经用户同意:不要自动
git commit/git push(含 Gitee/GitHub/gh-pages),等到用户明确说“提交/推送”再执行。 - 不要自动更新文档:API 文档、README、更新日志等,只有用户明确指定时才更新;不要顺手自动改。
- 每次提交信息要如实描述本次改动。
Bug 处理原则(最高优先级)
遇到任何 bug(无论轻重缓急),先定位根源,再从根源修复:
- 绝不允许用“新机制”让 bug 无法触发,来掩盖问题(那是掩盖,不是修复)。
- 如果根源确实在外部(Windows API / 系统 / 第三方库),才考虑绕过它,并在文档中明确标注“这是对外部问题的规避”。
- 如果根源在本项目内部代码,必须找到它并从根源修复。
- 如果找不到根源:如实说明“找不到,未定位”,交由用户(或用户的其他分析)定位;找到后再修复。绝不猜测、绝不用“最可疑”下结论、绝不靠引入机制来掩盖。
布局 / 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/DSLcorner()不再提供;需要自定义圆角的用户自行调用 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返回 RAIIHookHandle(析构自动断开);想长期有效就持有它;库内部固定钩子用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,不要把库专用逻辑写进它)。