原生模板系统规范¶
意图¶
使用由 Astryx 模板构建的原生应用的用户,会获得与 Web 模板相同的模板行为:在相同的步骤之后,看到相同的文字、值、验证和状态。每个原生平台都用其自身的控件和惯例来绘制该模板。
原生模板是面向单一平台的普通源代码,拥有自己的状态,就像目录模板之于 Web 一样。用户从 Astryx 仓库手动将其复制到自己的应用中,之后便完全拥有它;Astryx 不会为原生模板发布任何内容。一个脚本化场景让每个原生模板与其所镜像的 Web 模板保持同步。
非目标¶
- 哪些模板会获得原生版本,以及以什么顺序获得。
- 组件契约以及组件在平台上的绘制方式(
spec:AST-082、spec:AST-093)。 - 通过 CLI 将原生模板复制到应用中。
- 保存或同步模板的数据、登录和产品后端。
- 由通用组件树而非模板构建的屏幕。
- 只要满足此契约,等效的内部实现仍然有效。
需求¶
- FR1 — 一个原生模板镜像一个目录模板。 原生模板保存在
@astryxdesign/native源代码树中,位于其平台包的版本化模板目录中,例如swift-ios-<n>/templates/,并通过其 id 指定它所镜像的目录页面模板。 - FR2 — 原生模板是面向平台的普通源代码。 它用所属平台的语言维护自己的状态和逻辑,并使用该平台的 Astryx 组件进行绘制(
spec:AST-093)。它与 Web 模板或其他平台不共享任何模板逻辑、状态或按模板生成的类型。 - FR3 — 一个场景让 Web 与原生模板保持同步。 每个原生模板只有一个脚本化场景:每一步是一个通过角色和无障碍名称定位的手势,以及该手势后用户看到的文字、值、验证和状态。该场景在目录 Web 模板和每个原生版本上原样回放,并且每一步后都显示出预期结果。它就是该模板在
spec:AST-082/FR12下的场景。场景及其检查随原生模板的源代码一起存放,并随@astryxdesign/native的测试一起运行:如果目录变更破坏了该场景,原生模板就会失败,并会更新以匹配,且绝不会阻塞该目录变更。 - FR4 — 目录不因原生模板而改变。 无论是否有原生模板镜像某个目录模板,该目录模板的源代码、元数据和
astryx template输出都保持不变。@astryxdesign/core或@astryxdesign/cli中没有任何内容导入原生模板(spec:AST-082/FR14)。 - FR5 — 原生模板不随任何产物发布。 原生模板源代码、其测试和场景都被排除在每一个已发布产物之外:npm 包的文件、每个包导出和入口点,以及每个 Swift 产品;npm 包的
files会排除所有模板目录。它们只作为源代码存在于 Astryx 仓库中,由用户手动复制到自己的应用中,应用在运行时永远不会依赖 Astryx 来获取原生模板。目录模板则不同:它们随@astryxdesign/cli一起发布,并通过astryx template触达用户(architecture:template-authoring/INV8)。
平台支持¶
- 受支持的功能/引擎最低版本:每个原生模板以所属平台包的最低版本为目标,例如
swift-ios-<n>对应 iOS 17。Web 最低版本不变。 - 不受支持的行为:如果某个平台没有某模板的原生版本,那么该平台就没有对应的源代码,Astryx 也不会在该位置渲染任何内容。
- 浏览器证据:FR3 在浏览器中于目录 Web 模板上回放场景;原生相关声明则通过在设备上执行相同的回放来证明。
当前状态影响¶
- 诸如
swift-ios-<n>之类的版本化平台包尚不存在于 main 上;唯一的平台包是packages/native/apple/,其中没有任何模板。当某个平台包新增模板目录时,FR5 要求@astryxdesign/native的files将其排除在外。 @astryxdesign/native将在每个平台包的模板目录中新增原生模板,每个模板都带有一个场景。- 不会有目录模板、CLI 命令、已发布产物或架构记录发生变化。
- 目前还没有任何原生模板带有场景。
验证¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 |
|---|---|---|---|
| FR1 | 原生包检查:每个原生模板都引用一个存在的目录模板 | 一个带有 iOS 版本的模板 | 某个原生模板引用了不存在的目录 id |
| FR2 | 对每个原生模板进行源代码审查和依赖检查 | 模板的状态、验证和文本 | 某个原生模板导入了与 Web 或其他平台共享的模板逻辑或按模板生成的类型 |
| FR3 | 在目录 Web 模板和每个原生版本上回放场景 | 每个模板场景的每一步 | 任一原生版本或 Web 模板在某一步后显示不同结果,或目录变更因此被阻塞 |
| FR4 | 对使用和不使用原生模板时的 Catalog 与 CLI 输出进行比较,并检查依赖关系 | 每个目录模板都由一个原生模板镜像 | 目录源码、元数据或复制输出不一致,或核心或 CLI 引入了原生模板 |
| FR5 | npm pack 对 @astryxdesign/native 生成的文件列表、其 files 与导出映射,以及每个 Swift 包的产物 |
每个原生模板、其测试及其场景 | 打包的文件、导出、入口点或 Swift 产物包含或暴露了原生模板源码 |
决策日志¶
DEC-1 — 目录 Web 模板与原生模板保持分离¶
参考: spec:AST-091/DEC-1
决策者: cixzhang, 2026-10-23
原生支持目前处于实验阶段,因此目录 Web 模板保持原样,原生模板保留各自的独立状态。通过一致性场景而非共享实现来保持 Web 与原生行为一致,Web 调用方不会因原生工作而承受任何变更或风险。
推迟:由 Web 与原生模板共享的单一实现,待原生支持离开金丝雀渠道时再予考虑(spec:AST-082/FR15)。
DEC-2 — 原生模板通过克隆提供,不附带任何产物¶
参考: spec:AST-091/DEC-2
决策者: cixzhang, 2026-10-23
模板是起点,用户克隆后即拥有它们。应用在运行时从 Astryx 为原生模板导入的任何内容(代码或逻辑)都会成为调用方依赖的 API,而 Astryx 必须保持其稳定,因此原生模板仅提供源码。
已否决:由模板各个原生版本共享的可移植视图模型,因为那属于 Astryx 需要发布和维护的模板逻辑。
未决问题¶
目前没有未决问题。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx