---
title: "手册首页 — zenit Zig UI 文档"
description: "用 Zig 构建真正原生的 macOS 桌面界面。zenit 把窗口、GPU 渲染、文本、输入法与无障碍收进一个清晰的 UI 模型；"
url: https://zenit.z.express/zh/docs
language: zh-CN
alternate_en: https://zenit.z.express/docs.md
alternate_es: https://zenit.z.express/es/docs.md
alternate_ja: https://zenit.z.express/ja/docs.md
alternate_ko: https://zenit.z.express/ko/docs.md
alternate_fr: https://zenit.z.express/fr/docs.md
alternate_de: https://zenit.z.express/de/docs.md
project: zenit v0.1.0-alpha (Zig 0.15.2, macOS)
source: https://github.com/version-next/zenit
---

# zenit 开发手册

用 Zig 构建真正原生的 macOS 桌面界面。zenit 把窗口、GPU 渲染、文本、输入法与无障碍收进一个清晰的 UI 模型；这份手册带你从第一扇窗口走到可维护的生产应用。

[5 分钟开始](https://zenit.z.express/zh/docs/guide/getting-started)

$zig build run

**0.15.2**Zig 版本

**Metal**当前 GPU 后端

**2 tiers**公开 API：ui.X 与 ui.<group>.X

`src/main.zig`

```zig
const std = @import("std");
const ui = @import("ui");
const App = @import("zenit_app").App;

fn mountUi(cx: *ui.Cx, _: *ui.Scope) anyerror!*ui.Node {
    return ui.text(cx, "Hello, zenit!", .{
        .font_size = cx.tokens.font_size.xxxl,
        .color = cx.tokens.color.fg_primary,
    });
}

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();

    const app = try App.init(gpa.allocator(), .{
        .window = .{ .title = "Hello" },
    });
    defer app.deinit();
    try app.runWith(mountUi);
}
```

用 Claude Code 或其他 Agent 开发？先装上 zenit UI dev Skill。

它把这份手册、组件选型表和真实项目踩过的坑打包成 Agent 能按需加载的说明，写出的代码直接符合 zenit 的约定。

[下载 Skill.zip · 54 KB](https://zenit.z.express/downloads/zenit-ui-dev.zip)[安装说明](https://zenit.z.express/zh/docs/guide/ai-skill)

## 推荐学习路径

按顺序完成一次，约 45 分钟，你就拥有独立开发 zenit 应用所需的完整心智模型。

[01跑起第一扇窗口连接依赖、挂载 UI、构建并运行。10 min →](https://zenit.z.express/zh/docs/guide/getting-started)[02理解节点与布局用 box、stack、text 组织界面。12 min →](https://zenit.z.express/zh/docs/guide/ui-tree)[03让数据驱动界面Signal、Memo 与 Effect 的协作。12 min →](https://zenit.z.express/zh/docs/guide/reactivity)[04建立样式体系Token、具名样式与 Recipe。11 min →](https://zenit.z.express/zh/docs/guide/styling)

## 你将使用的架构

应用只依赖稳定的公开层，平台与渲染细节由 zenit 接管。

LAYERS

`zenit.attach(dep, exe)` 只给你的可执行文件加上 `ui` 与 `zenit_app` 两个模块导入，并编译原生桥接、链接系统框架。内部模块不在应用的构建图里，不是「约定不要用」，而是根本导入不到。

## 不只是一组 API

这三项能力贯穿运行时、文本与工程工具；每一项都有可运行的演示和真实窗口证据。

[DATA FLOWSignal 精确更新不重建虚拟树、不做整树 diff；依赖直接找到订阅它的节点。看概念动画 →](https://zenit.z.express/zh/docs/guide/reactivity#signal-not-diffing)[TEXT ENGINEUnicode 17 + IMEUAX #9 双向文本、UAX #29 字素边界，以及 preedit / commit 的端到端输入路径。看一致性证据 →](https://zenit.z.express/zh/docs/guide/text-engine)[TOOLING可观测的真实窗口 E2E按语义定位节点、虚拟鼠标、Retina PNG 截图，以及从 drawable 直接录制的 MP4。看测试录像 →](https://zenit.z.express/zh/docs/advanced/e2e)

## 三条开发原则

遵守它们，代码能在 zenit 快速演进的阶段保持清晰。

**只从公开层导入**

应用代码使用 `ui.*`、`ui.<group>.*` 与 `zenit_app.App`，不要深入内部目录。

**让数据决定 UI**

持久状态放进 Signal 或绑定状态；派生值用 Memo，副作用用 Effect。

**Token 优先**

颜色、字号、间距与圆角来自主题；确需脱离刻度时，用 `ui.arb` 明确表达。