docs: make Chinese README the default

2026-07-13 10:19:50 +00:00
parent 31be210389
commit c9cf0e5597
1 changed files with 56 additions and 50 deletions
@@ -1,14 +1,20 @@
+<!-- WEHUB_ZH_README -->
+> [!NOTE]
+> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
+> [English](./README.en.md) · [原始项目](https://github.com/vercel-labs/zero-native) · [上游 README](https://github.com/vercel-labs/zero-native/blob/HEAD/README.md)  
+> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
+
 # Native SDK

-**Native SDK is the complete toolkit for building native desktop applications.**
+**Native SDK 是构建原生桌面应用的完整工具包。**

-Native SDK exists because expressive UI and native performance should not be competing goals. Developers often choose web-based runtimes because they offer freedom, speed and control over the product experience. But that freedom often comes with a heavy runtime. Native SDK keeps the expressive authoring model and replaces the runtime with native rendering.
+Native SDK 的诞生，是因为富有表现力的 UI 与原生性能本不应互相掣肘。开发者常常选择基于 Web 的运行时，因为它们在产品体验上提供了自由、速度与掌控力。但这种自由往往伴随着沉重的运行时负担。Native SDK 保留了富有表现力的创作模型，并以原生渲染取代运行时。

-Views are declarative markup in `.native` files, logic is plain TypeScript compiled to native code at build time — or Zig, first-class by choice — and Native SDK's own engine draws every pixel into real OS windows. No browser, no WebView, no JS runtime in the binary: Zig is how everything works, TypeScript and Native markup are how apps are authored.
+视图是 `.native` 文件中的声明式标记，逻辑是普通的 TypeScript，在构建时编译为原生代码——或可选地一等支持 Zig——而 Native SDK 自有引擎将每一个像素绘制到真实的操作系统窗口中。二进制中无浏览器、无 WebView、无 JS 运行时：Zig 驱动一切运转，TypeScript 与 Native 标记则是应用的创作方式。

 <picture>
  <source media="(prefers-color-scheme: dark)" srcset=".github/assets/soundboard-dark.webp">
-  <img src=".github/assets/soundboard-light.webp" alt="The Soundboard example app rendered by the Native SDK engine: a music library with album cover art, search, and a playback bar" width="100%">
+  <img src=".github/assets/soundboard-light.webp" alt="由 Native SDK 引擎渲染的 Soundboard 示例应用：音乐库，含专辑封面、搜索与播放栏" width="100%">
 </picture>

 <table>
@@ -16,29 +22,29 @@ Views are declarative markup in `.native` files, logic is plain TypeScript compi
    <td width="70%">
      <picture>
        <source media="(prefers-color-scheme: dark)" srcset=".github/assets/notes-dark.webp">
-        <img src=".github/assets/notes-light.webp" alt="The Notes example app rendered by the Native SDK engine: a three-pane notes manager with folders, a note list, and an open note" width="640">
+        <img src=".github/assets/notes-light.webp" alt="由 Native SDK 引擎渲染的 Notes 示例应用：三栏笔记管理器，含文件夹、笔记列表与打开的笔记" width="640">
      </picture>
    </td>
    <td width="30%">
      <picture>
        <source media="(prefers-color-scheme: dark)" srcset=".github/assets/calculator-dark.webp">
-        <img src=".github/assets/calculator-light.webp" alt="The Calculator example app rendered by the Native SDK engine: a finished calculation above a full keypad" width="270">
+        <img src=".github/assets/calculator-light.webp" alt="由 Native SDK 引擎渲染的 Calculator 示例应用：完整键盘上方显示已完成的计算结果" width="270">
      </picture>
    </td>
  </tr>
 </table>

-<sub>Soundboard, Notes, and Calculator from <a href="./examples">examples/</a> — every pixel drawn by the Native SDK engine, captured through its deterministic reference renderer. The images follow your color scheme.</sub>
+<sub>上图 Soundboard、Notes 与 Calculator 来自 <a href="./examples">examples/</a> —— 每一像素均由 Native SDK 引擎绘制，通过其确定性参考渲染器捕获。图片会随你的配色方案切换。</sub>

-## Quick start
+## 快速入门

-Install the CLI:
+安装 CLI：

 ```bash
 npm install -g @native-sdk/cli
 ```

-Create and run an app:
+创建并运行应用：

 ```bash
 native init my_app
@@ -46,7 +52,7 @@ cd my_app
 native dev
 ```

-A native window opens with a working counter. The whole app is three files of truth — view, logic, manifest — and no build config. The view is `src/app.native`, a markup file that binds values and dispatches messages (the counter row at its heart):
+会打开一个原生窗口，内含可用的计数器。整个应用只有三个真相文件——视图、逻辑、清单——且无需构建配置。视图是 `src/app.native`，一个绑定值并分发消息（核心是计数器行）的标记文件：

 ```html
 <row gap="8" main="center" cross="center" grow="1">
@@ -56,7 +62,7 @@ A native window opens with a working counter. The whole app is three files of tr
 </row>
 ```

-All logic lives in `src/core.ts`: a `Model` interface, a `Msg` union, and one pure `update` function — the only place state changes, plain TypeScript compiled to native code at build time:
+所有逻辑位于 `src/core.ts`：一个 `Model` 接口、一个 `Msg` 联合类型，以及一个纯 `update` 函数——唯一改变状态之处，普通 TypeScript 在构建时编译为原生代码：

 ```ts
 export function update(model: Model, msg: Msg): Model {
@@ -71,65 +77,65 @@ export function update(model: Model, msg: Msg): Model {
 }
 ```

-Prefer Zig for the core? `native init my_app --template zig-core` scaffolds the same app with `src/main.zig` — same loop, same runtime, first-class by choice.
+更喜欢用 Zig 编写核心？`native init my_app --template zig-core` 会以 `src/main.zig` 搭建同款应用——相同循环、相同运行时，可选的一等支持。

-Edit `src/app.native` while `native dev` runs and the window updates in place, keeping your state. `native dev --core` runs the TypeScript core under node for instant logic checks, `native check` validates the core and every view in milliseconds without building, and `native build` produces an optimized release binary.
+在 `native dev` 运行期间编辑 `src/app.native`，窗口会原地更新并保留状态。`native dev --core` 在 node 下运行 TypeScript 核心以即时校验逻辑，`native check` 在毫秒内校验核心与每个视图且无需构建，`native build` 则生成优化的发布版二进制。

-Read the full guide at [native-sdk.dev/quick-start](https://native-sdk.dev/quick-start).
+完整指南见 [native-sdk.dev/quick-start](https://native-sdk.dev/quick-start).

-## What you get
+## 你将获得什么

-**Beautiful by default** — Great software should not start from a blank slate. The built-in component catalog — buttons, tabs, text fields, dialogs, charts, virtual lists, and more — ships with considered typography, spacing, and color, so the app `native init` scaffolds already looks intentional the first time its window opens.
+**默认即精美** — 优秀的软件不应从白纸开始。内置组件目录——按钮、标签页、文本框、对话框、图表、虚拟列表等——配备精心斟酌的字体、间距与颜色，因此 `native init` 搭建的应用在窗口首次打开时便已显得有意为之。

-**Customizable by design** — Your app should have its own identity, not ours. Styling is design tokens end to end: color, radius, and typography resolve by name, re-resolve live when the theme changes, and can be replaced wholesale — `examples/soundboard` and `examples/deck` are the same music player separated only by tokens and a chrome pass.
+**为定制而设计** — 你的应用应拥有自身身份，而非我们的。样式全程基于设计令牌（design tokens）：颜色、圆角与字体按名称解析，主题变更时实时重新解析，并可整体替换——`examples/soundboard` 与 `examples/deck` 是同一款音乐播放器，仅通过令牌与 chrome 处理区分。

-**Native from the start** — Every interface is rendered without a browser or WebView. The engine draws into real OS windows while scroll physics, menus, dialogs, the tray, and text input stay with the operating system, and markup compiles into the executable at build time, so a release build carries no parser or interpreter — the scaffolded counter app builds to a single binary a few megabytes small.
+**从一开始就原生** — 每个界面均无需浏览器或 WebView 即可渲染。引擎绘制到真实操作系统窗口，滚动物理、菜单、对话框、托盘与文本输入均交由操作系统处理，标记在构建时编译进可执行文件，因此发布构建不携带解析器或解释器——脚手架计数器应用可构建为仅几 MB 的单一二进制。

-**Predictable state** — State changes should be explicit, inspectable and easy to reason about. Events produce messages, messages update state, and state renders the interface; markup can bind and dispatch but never mutate. The loop is so deterministic that `native automate record` journals a session and `replay` reproduces it headlessly, verified frame by frame against state fingerprints.
+**可预测的状态** — 状态变更应显式、可检查且易于推理。事件产生消息，消息更新状态，状态渲染界面；标记可绑定与分发但绝不直接变更。循环如此确定，`native automate record` 可记录会话，`replay` 可无头复现，并逐帧对照状态指纹校验。

-**Simple authoring** — Interfaces should be easy to read, easy to write and easy to generate. Views are elements, flex layout, `{bindings}`, and expressions like `selected="{f == filter}"`, and `native check` validates every view against your app's actual `Model` and `Msg` — bindings, iterables, message tags — in milliseconds, with `file:line:column` errors that teach.
+**简洁的创作** — 界面应易于阅读、编写与生成。视图由元素、flex 布局、`{bindings}` 以及类似 `selected="{f == filter}"` 的表达式构成，`native check` 在毫秒内根据应用实际的 `Model` 与 `Msg`——绑定、可迭代对象、消息标签——校验每个视图，并以 `file:line:column` 错误提供可学习的反馈。

-**AI is part of the workflow** — Native SDK is designed for a world where humans and AI agents build software together. Every app embeds an automation server, so any agent can read accessibility snapshots, drive widgets, assert on live state, and take deterministic screenshots of the running window; accessibility findings are machine-checked in `native check`; and the CLI ships the agent skills that teach all of it (`native skills list`).
+**AI 是工作流的一部分** — Native SDK 面向人类与 AI 智能体共同构建软件的世界而设计。每个应用内嵌自动化服务器，任意智能体均可读取无障碍快照、驱动控件、断言实时状态，并对运行中的窗口进行确定性截图；无障碍检查结果在 `native check` 中由机器校验；CLI 还提供传授这一切的智能体技能（`native skills list`）。

-## Examples
+## 示例

-The apps pictured above live in [examples/](./examples), most as zero-config projects — `app.zon` plus `src/`, no build files — run straight from their directory with `native dev`.
+上文所示应用位于 [examples/](./examples)，多数为零配置项目——`app.zon` 加 `src/`，无构建文件——使用 `native dev` 可直接在其目录运行。

-| Example | What it shows |
+| 示例 | 展示内容 |
 | --- | --- |
-| [`calculator`](./examples/calculator) | A complete small app: markup keypad, keyboard input, chrome shortcuts, theming. |
-| [`notes`](./examples/notes) | Persistence through the effects channel: debounced writes, restore on boot, dialogs, search. |
-| [`soundboard`](./examples/soundboard) | Album grid with decoded cover art, context menus, timers, and a custom theme. |
-| [`deck`](./examples/deck) | The soundboard player rebuilt as a dense hardware chassis: two windows, same widgets, different tokens. |
-| [`feed`](./examples/feed) | A 100,000-row list, virtualized with runtime-owned scrolling. |
+| [`calculator`](./examples/calculator) | 完整的小型应用：标记键盘、键盘输入、chrome 快捷键、主题。 |
+| [`notes`](./examples/notes) | 通过 effects 通道实现持久化：防抖写入、启动时恢复、对话框、搜索。 |
+| [`soundboard`](./examples/soundboard) | 含解码封面图的专辑网格、上下文菜单、计时器与自定义主题。 |
+| [`deck`](./examples/deck) | 将 soundboard 播放器重构为紧凑的硬件机箱：双窗口、相同控件、不同令牌。 |
+| [`feed`](./examples/feed) | 10 万行列表，由运行时拥有的滚动实现虚拟化。 |

-The full catalog in [examples/README.md](./examples/README.md) also covers guarded OS capabilities, GPU surfaces, WebView composition, web-frontend shells, and the iOS/Android embed hosts.
+[examples/README.md](./examples/README.md) 中的完整目录还涵盖受保护的 OS 能力、GPU 表面、WebView 合成、Web 前端壳，以及 iOS/Android 嵌入宿主。

-## Platforms
+## 平台

-macOS is the primary development platform and carries the deepest support: Metal presentation, OS scroll physics, native context menus, app menus, tray, and dialogs. Linux runs the full showcase through the deterministic software renderer in real windows, with pointer, keyboard, scroll, IME composition, and HiDPI; Windows runs on a Win32 host with IME composition and is exercised in CI, including real input injection. Mobile support is experimental: iOS is simulator-proven through the embed library and Android cross-compiles with the full embed ABI, but APIs and tooling on both are still evolving — desktop is the mature surface. WebView surfaces coexist on every desktop platform. The [platform support matrix](https://native-sdk.dev/platform-support) documents exactly what each host supports today.
+macOS 是主要开发平台，支持最为深入：Metal 呈现、系统滚动物理、原生上下文菜单、应用菜单、托盘与对话框。Linux 通过确定性软件渲染器在真实窗口中运行完整展示，支持指针、键盘、滚动、IME 输入法合成与 HiDPI；Windows 运行于 Win32 宿主，支持 IME 输入法合成，并在 CI 中受测，包括真实输入注入。移动端支持尚属实验性：iOS 已通过嵌入库在模拟器验证，Android 可交叉编译并具备完整嵌入 ABI，但两端的 API 与工具仍在演进——桌面是成熟平台。WebView 表面在所有桌面平台上共存。[platform support matrix](https://native-sdk.dev/platform-support) 精确记录了各宿主当前的支持情况。

-## Documentation
+## 文档

-The full documentation is at [native-sdk.dev](https://native-sdk.dev).
+完整文档位于 [native-sdk.dev](https://native-sdk.dev).

- [Quick Start](https://native-sdk.dev/quick-start) — install to a running, tested app
- [Philosophy](https://native-sdk.dev/philosophy) — the six principles behind the toolkit
- [App Model](https://native-sdk.dev/app-model) — the model/message/update loop, wiring, and hot reload
- [TypeScript Cores](https://native-sdk.dev/typescript) — the app-core subset, effects, subscriptions, and the node dev loop
- [Native UI](https://native-sdk.dev/native-ui) — every element, attribute, and pattern in the markup
- [Components](https://native-sdk.dev/components) — the component catalog
- [State & Data Flow](https://native-sdk.dev/state) — derive-don't-store, bindings, and text editing
- [Testing](https://native-sdk.dev/testing) — full-loop UI tests, headless on any machine
- [Automation](https://native-sdk.dev/automation) — snapshots, widget driving, record/replay, screenshots
- [Capabilities](https://native-sdk.dev/capabilities) — guarded OS services: notifications, clipboard, dialogs, credentials
- [Packaging](https://native-sdk.dev/packaging) — from binary to distributable app
- [Platform Support](https://native-sdk.dev/platform-support) — what each host supports today
+- [快速入门](https://native-sdk.dev/quick-start) — 安装并运行可测试的应用
+- [设计理念](https://native-sdk.dev/philosophy) — 工具包背后的六项原则
+- [应用模型](https://native-sdk.dev/app-model) — model/message/update 循环、连线与热重载
+- [TypeScript 核心](https://native-sdk.dev/typescript) — app-core 子集、effects、subscriptions 与 Node 开发循环
+- [原生 UI](https://native-sdk.dev/native-ui) — 标记语言中的全部元素、属性与模式
+- [组件](https://native-sdk.dev/components) — 组件目录
+- [状态与数据流](https://native-sdk.dev/state) — derive-don't-store（派生而非存储）、绑定与文本编辑
+- [测试](https://native-sdk.dev/testing) — 全链路 UI 测试，可在任意机器上无头运行
+- [自动化](https://native-sdk.dev/automation) — 快照、控件驱动、录制/回放、截图
+- [系统能力](https://native-sdk.dev/capabilities) — 受保护的 OS 服务：通知、剪贴板、对话框、凭据
+- [打包分发](https://native-sdk.dev/packaging) — 从二进制到可分发应用
+- [平台支持](https://native-sdk.dev/platform-support) — 各宿主平台当前支持情况

-## Contributing
+## 贡献

-Native SDK is pre-1.0: APIs still move, and the toolkit is evolving quickly. Bug reports and focused pull requests are welcome — for larger changes, open an issue first so the design can be discussed. See [CONTRIBUTING.md](./CONTRIBUTING.md) for the development setup and local checks.
+Native SDK 目前为 pre-1.0 版本：API 仍在调整，工具包也在快速迭代。欢迎提交 bug 报告和针对性 pull request；若改动较大，请先开 issue 以便讨论设计方案。开发环境与本地检查见 [CONTRIBUTING.md](./CONTRIBUTING.md)。

-## License
+## 许可证

 [Apache-2.0](./LICENSE)