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

站点构建只生成静态产物,不发布网站。所有平台使用同一入口:在 docs-site/ 运行 bun run ci。每次构建重新读取仓库源文档,生成页面、搜索数据、版本、原文下载与 AI 快照。

Gitee 流水线

Gitee 当前帮助文档描述的是通过 UI 编排流水线。仓库中的 .github/workflows/docs.yml 不会在 Gitee 自动执行,也不代表已经开通 Gitee 流水线。

在有流水线权限的 Gitee 项目中配置:

  1. 创建流水线,输入源选择本仓库,分支选择 main;如需要对贡献分支构建,增加对应分支条件。
  2. 触发条件选择代码变更 / Push。文档、站点源码、图片或 ZufyUIVersion.h 变化时需要构建;也可对所有推送触发。
  3. 构建任务选支持 Bun 1.4.5 的 Linux 环境,例如预装该版本的执行机或 oven/bun:1.4.5 容器。任务从仓库根目录执行:
cd docs-site
bun install --frozen-lockfile
bun run ci
  1. 配置制品收集目录为仓库根目录下 docs-site/out/,保留目录结构;不添加部署任务。
  2. 手动运行一次确认成功,再通过一次推送验证触发。流水线配额、环境镜像和可用插件取决于账户配置。

官方说明:流水线介绍、创建流水线、触发运行。本次本地生成不启用账户服务、不消耗云端构建额度。

GitHub 镜像

仓库附带 .github/workflows/docs.yml。代码存在于 GitHub 且 Actions 已启用时,文档或站点相关的 Push / PR 会运行构建;也可手动触发。成功后下载 zufyui-docs-static 制品,保留 14 天。工作流只有读取仓库和上传制品步骤,没有 Pages 部署权限或发布步骤。

Gitee → GitHub 镜像同步需要另外配置;本项目不会暗中复制仓库或创建镜像。

本地内容自动更新

bun run dev 监听 Markdown 和版本文件变化,自动重新生成内容快照;Next.js 对界面源码热更新。若生成失败,终端显示错误,修正源文件后自动重试。

验收入口

  • bun run check:内容覆盖、内部目标、资源和 TypeScript。
  • bun test:章节映射、AI 文档链接、旧格式转换和全文搜索。
  • bun run build:Next.js 静态导出。
  • bun scripts/verify-export.ts:每篇正文确实进入 HTML、所有原始下载文件与仓库一致、导航数据的文件名与内容完整。
  • bun run preview:仅用静态文件服务器检查 http://127.0.0.1:4318/。

首次自动构建需平台实际运行成功才能称为已启用。仅提交工作流文件不等同于云端验证通过。

Release 交付

框架、文档原稿和 docs-site/ 源码在同一仓库维护。依赖、编译缓存、静态导出和二进制包不提交到源码分支;按 ZufyUIVersion.h 的版本将产物上传到 Release。

先完成 Windows x64 Release 构建与自检,以及文档站 bun run ci,然后在仓库根目录执行(Python 环境需安装 fonttools 和 Pillow):

python tools/package_release.py --out releases/v1.29.1 --docs

--docs 同时打包 docs-site/out/,检查版本并拒绝未归一化的导航文件目录。交付包括 Windows x64 ZIP(Demo、调试器和 Python 调试桥)、独立 demo.exe、静态站 ZIP、版本与源码提交清单,以及 SHA-256 校验文件。打包命令不会自行提交、推送或发布;Release 上传由维护者授权执行。

静态 ZIP 解压目录中直接包含 index.html。可在解压目录执行 python -m http.server 4320 --bind 127.0.0.1,访问 http://127.0.0.1:4320/zh/;托管时上传整个解压目录,保留所有 __next.*.txt 文件。

查看源文件docs/site-ci.md