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

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

## 命名空间与头文件

- 所有内容位于 `namespace ZufyUI`。
- 头文件**按使用分层**:
  - `ZufyUI.h`:核心——类型 / 信号槽 / 字体 / 元素基类 / 布局 / 菜单 / 窗口。
  - `ZufyUIAcrylic.h`:手写 DComp 合成效果 + 官方亚克力/云母配方(由 `ZufyUI.h` 包含)。
  - `ZufyUIWidgets.h`:基础控件(Label/Button/TextBox/TextEdit/ComboBox/…/ScrollViewer/TabView/图标…),内部 `#include "ZufyUI.h"`。
  - `ZDataViewer.h`:数据视图(ListView/TableView/TreeView),依赖前两者。
  - `ZufyUICharts.h`:**图表(BarChart/LineChart/PieChart)**,依赖 `ZufyUI.h`。
  - `ZufyUIImages.h`:`Image` / `ImageManager`(图片加载与设备缓存)。
  - `ZufyUIIcons.h`:`FontIcon` 字形控件(`Icon` 枚举本身在 `ZufyUIWidgets.h`)。
  - `ZufyUIWindowTool.h`:窗口周边(标题栏 / MessageBox / 托盘 / 系统对话框 / 无障碍提供程序 / 调试通道);**自 v1.20.0 起自身包含 `ZufyUIWidgets.h`**,可单独包含;末尾包含 `ZufyUIHwndView.h`。
  - `ZufyUIHwndView.h`:原生 HWND 宿主 `HwndView`(WebView2 / 摄像头 / 第三方 / 进程外窗口)。
  - `ZufyUIDragDrop.h`:拖放(由 `ZufyUI.h` 末尾包含)。
  - `ZufyUIDsl.h`:可选**链式构造 DSL**(纯附加,不修改任何现有控件)。
- 全部是**纯头文件**;`#pragma comment(lib, ...)` 会自动链接 `d2d1 / dwrite / dwmapi / imm32 / winmm`。
- **源码编码**:含中文的 `.h` / `.cpp` 必须存为 **UTF-8 带 BOM**(否则 MSVC 按本地代码页解析,报 `C2143/C2259/C2888/C4819`);`.md` / `.tex` 存为 **UTF-8 无 BOM**。需要无 BOM / 纯 ASCII 副本时,用 `tools/export_ascii.py` 生成 `dist/ascii`(不提交;详见 README「纯 ASCII 导出」)。

## 单位

- 所有坐标与尺寸都是 **DIP**(设备无关像素),不是物理像素。
- 框架在绘制前用内部 `Snap()` 吸附到物理像素网格;你写代码时**不需要**自己做 DPI 换算。
- 鼠标事件坐标也是 DIP。屏幕坐标只在系统 API(`Create`、`ShowAt`、`FileDialog`)里出现。

###block_red_start
**易错**

###block_red_end

## 对象模型与生命周期

- 控件一律 `std::shared_ptr<T>` 拥有,用 `std::make_shared<T>()` 创建。
- 通过布局/容器的 `AddChild()` 挂到父容器;父容器保存子元素的 `shared_ptr`,**父容器存活期间子元素不会释放**。
- 脱离布局后若没有其它 `shared_ptr`,元素即回收;元素析构会自动释放自身离屏缓存与已注册连接(内部 `ConnectionGroup`)。

###block_green_start
**推荐的所有权模型**

控件由 `std::shared_ptr` 拥有;父容器通过 `AddChild` 持有子元素。跨层引用用裸指针或 `weak_ptr`,不要反向持有父容器的 `shared_ptr`,也不要让两个容器同时拥有同一个控件。
###block_green_end

###block_red_start
**易错**

- `UIElement::SetParent` 存的是**裸指针**(非拥有);所有权永远在容器/`Application` 的 `shared_ptr` 上。窗口在元素里只以 **window id** 记录,避免窗口先销毁导致 UAF。
###block_red_end

## 信号与事件

- 用 `Connect(signal, slot)` 绑定,返回 `Connection`,默认随宿主元素析构自动断开。
- 槽可以是任意可调用对象(lambda / 函数指针 / `std::function`)。

###block_red_start
**易错**

- 不要用“按值捕获宿主自身 `shared_ptr`”的 lambda 连接宿主自己的信号 → 引用环,整棵子树泄漏。详见「事件与信号」章。
###block_red_end

## 默认值体系

- 每个控件有 `inline static` 的 `Default*` 静态字段(如 `Button::DefaultSize`)。
- `static SetDefault*()` 修改后**只影响之后新建的实例**;实例级 setter 只影响该实例。

###block_red_start
**易错**

- 静态默认字段是**进程全局**的;多窗口若需要不同观感,请在创建前设置或逐实例 setter。
###block_red_end

## 禁用、焦点、缓存三个通用概念(贯穿所有控件)

- **启用/禁用**:`UIElement::SetEnabled(false)` 让该元素及子树不可交互(鼠标/键盘被拦截),控件需自己用 `IsEffectivelyEnabled()` 决定是否画灰。**禁用不改变布局**(仍占位)。`SetEnabled(false)` ≠ `SetVisible(false)`。
- **焦点**:只有 `IsFocusable()` 为 true 的元素能拿键盘焦点。窗口按 Tab 遍历聚焦元素;焦点环只在“通过 Tab 获得焦点”时显示,鼠标点击焦点不显示。
- **离屏缓存**:见「元素基类」的“缓存机制”。默认开启;动画频繁/实例极多的控件用 `SetUseCache(false)` 关掉以省显存。
第 1 章

约定

命名空间、单位、生命周期、版本与易错标注约定

颜色与标记

命名空间与头文件

单位

易错

对象模型与生命周期

推荐的所有权模型

控件由 std::shared_ptr 拥有;父容器通过 AddChild 持有子元素。跨层引用用裸指针或 weak_ptr,不要反向持有父容器的 shared_ptr,也不要让两个容器同时拥有同一个控件。

易错

  • UIElement::SetParent 存的是裸指针(非拥有);所有权永远在容器/Application 的 shared_ptr 上。窗口在元素里只以 window id 记录,避免窗口先销毁导致 UAF。

信号与事件

易错

  • 不要用“按值捕获宿主自身 shared_ptr”的 lambda 连接宿主自己的信号 → 引用环,整棵子树泄漏。详见「事件与信号」章。

默认值体系

易错

  • 静态默认字段是进程全局的;多窗口若需要不同观感,请在创建前设置或逐实例 setter。

禁用、焦点、缓存三个通用概念(贯穿所有控件)

↑