wehub-resource-sync
c9cf0e5597
9.5 KiB
Note
本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
Native SDK
Native SDK 是构建原生桌面应用的完整工具包。
Native SDK 的诞生，是因为富有表现力的 UI 与原生性能本不应互相掣肘。开发者常常选择基于 Web 的运行时，因为它们在产品体验上提供了自由、速度与掌控力。但这种自由往往伴随着沉重的运行时负担。Native SDK 保留了富有表现力的创作模型，并以原生渲染取代运行时。
视图是 .native 文件中的声明式标记，逻辑是普通的 TypeScript，在构建时编译为原生代码——或可选地一等支持 Zig——而 Native SDK 自有引擎将每一个像素绘制到真实的操作系统窗口中。二进制中无浏览器、无 WebView、无 JS 运行时：Zig 驱动一切运转，TypeScript 与 Native 标记则是应用的创作方式。
|
|
上图 Soundboard、Notes 与 Calculator 来自 examples/ —— 每一像素均由 Native SDK 引擎绘制，通过其确定性参考渲染器捕获。图片会随你的配色方案切换。
快速入门
安装 CLI：
npm install -g @native-sdk/cli
创建并运行应用：
native init my_app
cd my_app
native dev
会打开一个原生窗口，内含可用的计数器。整个应用只有三个真相文件——视图、逻辑、清单——且无需构建配置。视图是 src/app.native，一个绑定值并分发消息（核心是计数器行）的标记文件：
<row gap="8" main="center" cross="center" grow="1">
<button variant="secondary" on-press="decrement">-</button>
<text>{count}</text>
<button variant="primary" on-press="increment">+</button>
</row>
所有逻辑位于 src/core.ts：一个 Model 接口、一个 Msg 联合类型，以及一个纯 update 函数——唯一改变状态之处，普通 TypeScript 在构建时编译为原生代码：
export function update(model: Model, msg: Msg): Model {
switch (msg.kind) {
case "increment":
return { ...model, count: model.count + 1 };
case "decrement":
return { ...model, count: model.count - 1 };
case "reset":
return { ...model, count: 0 };
}
}
更喜欢用 Zig 编写核心？native init my_app --template zig-core 会以 src/main.zig 搭建同款应用——相同循环、相同运行时，可选的一等支持。
在 native dev 运行期间编辑 src/app.native，窗口会原地更新并保留状态。native dev --core 在 node 下运行 TypeScript 核心以即时校验逻辑，native check 在毫秒内校验核心与每个视图且无需构建，native build 则生成优化的发布版二进制。
完整指南见 native-sdk.dev/quick-start.
你将获得什么
默认即精美 — 优秀的软件不应从白纸开始。内置组件目录——按钮、标签页、文本框、对话框、图表、虚拟列表等——配备精心斟酌的字体、间距与颜色，因此 native init 搭建的应用在窗口首次打开时便已显得有意为之。
为定制而设计 — 你的应用应拥有自身身份，而非我们的。样式全程基于设计令牌（design tokens）：颜色、圆角与字体按名称解析，主题变更时实时重新解析，并可整体替换——examples/soundboard 与 examples/deck 是同一款音乐播放器，仅通过令牌与 chrome 处理区分。
从一开始就原生 — 每个界面均无需浏览器或 WebView 即可渲染。引擎绘制到真实操作系统窗口，滚动物理、菜单、对话框、托盘与文本输入均交由操作系统处理，标记在构建时编译进可执行文件，因此发布构建不携带解析器或解释器——脚手架计数器应用可构建为仅几 MB 的单一二进制。
可预测的状态 — 状态变更应显式、可检查且易于推理。事件产生消息，消息更新状态，状态渲染界面；标记可绑定与分发但绝不直接变更。循环如此确定，native automate record 可记录会话，replay 可无头复现，并逐帧对照状态指纹校验。
简洁的创作 — 界面应易于阅读、编写与生成。视图由元素、flex 布局、{bindings} 以及类似 selected="{f == filter}" 的表达式构成，native check 在毫秒内根据应用实际的 Model 与 Msg——绑定、可迭代对象、消息标签——校验每个视图，并以 file:line:column 错误提供可学习的反馈。
AI 是工作流的一部分 — Native SDK 面向人类与 AI 智能体共同构建软件的世界而设计。每个应用内嵌自动化服务器，任意智能体均可读取无障碍快照、驱动控件、断言实时状态，并对运行中的窗口进行确定性截图；无障碍检查结果在 native check 中由机器校验；CLI 还提供传授这一切的智能体技能（native skills list）。
示例
上文所示应用位于 examples/，多数为零配置项目——app.zon 加 src/，无构建文件——使用 native dev 可直接在其目录运行。
| 示例 | 展示内容 |
|---|---|
calculator |
完整的小型应用：标记键盘、键盘输入、chrome 快捷键、主题。 |
notes |
通过 effects 通道实现持久化：防抖写入、启动时恢复、对话框、搜索。 |
soundboard |
含解码封面图的专辑网格、上下文菜单、计时器与自定义主题。 |
deck |
将 soundboard 播放器重构为紧凑的硬件机箱：双窗口、相同控件、不同令牌。 |
feed |
10 万行列表，由运行时拥有的滚动实现虚拟化。 |
examples/README.md 中的完整目录还涵盖受保护的 OS 能力、GPU 表面、WebView 合成、Web 前端壳，以及 iOS/Android 嵌入宿主。
平台
macOS 是主要开发平台，支持最为深入：Metal 呈现、系统滚动物理、原生上下文菜单、应用菜单、托盘与对话框。Linux 通过确定性软件渲染器在真实窗口中运行完整展示，支持指针、键盘、滚动、IME 输入法合成与 HiDPI；Windows 运行于 Win32 宿主，支持 IME 输入法合成，并在 CI 中受测，包括真实输入注入。移动端支持尚属实验性：iOS 已通过嵌入库在模拟器验证，Android 可交叉编译并具备完整嵌入 ABI，但两端的 API 与工具仍在演进——桌面是成熟平台。WebView 表面在所有桌面平台上共存。platform support matrix 精确记录了各宿主当前的支持情况。
文档
完整文档位于 native-sdk.dev.
- 快速入门 — 安装并运行可测试的应用
- 设计理念 — 工具包背后的六项原则
- 应用模型 — model/message/update 循环、连线与热重载
- TypeScript 核心 — app-core 子集、effects、subscriptions 与 Node 开发循环
- 原生 UI — 标记语言中的全部元素、属性与模式
- 组件 — 组件目录
- 状态与数据流 — derive-don't-store（派生而非存储）、绑定与文本编辑
- 测试 — 全链路 UI 测试，可在任意机器上无头运行
- 自动化 — 快照、控件驱动、录制/回放、截图
- 系统能力 — 受保护的 OS 服务：通知、剪贴板、对话框、凭据
- 打包分发 — 从二进制到可分发应用
- 平台支持 — 各宿主平台当前支持情况
贡献
Native SDK 目前为 pre-1.0 版本：API 仍在调整，工具包也在快速迭代。欢迎提交 bug 报告和针对性 pull request；若改动较大，请先开 issue 以便讨论设计方案。开发环境与本地检查见 CONTRIBUTING.md。