原生组件指南系统规格¶
意图¶
使用 @astryxdesign/native 构建应用的用户,会获得外观和行为都如同其平台原生控件的组件;这些组件在平台留有空间的地方承载应用的品牌,并且每次都经过同样方式的检查。
构建原生组件的贡献者在同一个位置、以同一种形态为它编写一份简短规格;按照固定顺序遵循三条指南(原生优先,其次是平台自身的设计指南,最后是主题处理其余所有事项),并像每个其他原生组件一样,用相同的测试和截图证明结果。原生组件以 Swift 编写,面向 iOS 和 macOS。
本记录将 spec:AST-082 应用于单个原生组件的规格制定、构建、验证和审查工作,在此期间 @astryxdesign/native 仅处于 canary 阶段(spec:AST-082/FR15)。
非目标¶
- 哪种平台构建方式胜出。
spec:AST-082/FR12通过测量来决定。 - 支持的 OS 版本(
spec:AST-082/OQ4)和性能阈值(spec:AST-082/OQ1)。 - 组件的核心契约:其共享的 props、状态、文案和无障碍语义。组件自己的记录和
spec:AST-082/FR3拥有这些。 - Android 和 Windows 的指南(OQ1)。
- Web 组件和
@astryxdesign/core。 - 当满足此契约时,等效的内部实现仍然有效。
需求¶
- FR1 — 原生组件的规格与核心组件的规格放在一起。 每个原生组件的视图都位于其语言实现的目录中,该目录镜像了其核心组件根目录(核心源码目录):
<ComponentRoot>;当核心将组件放在自己的文件夹中时,它就是<Name>。因此,核心的Avatar/AvatarStatusDot也将 Swift AvatarStatusDot 视图放在Avatar/中。规格查找通过该目录将原生视图路由到其组件的记录,这就是该目录成为契约一部分的原因。其规格是核心组件文件夹下docs/specs/components/中的<Name>.<language>.spec.md,与核心记录(docs/specs/components/<ComponentRoot>/<Name>.spec.md)并列,如architecture:knowledge-contractsDEC-15 所规定的那样放置每个组件记录。每种语言有一个实现包;对于 Swift,那是packages/native/apple/,其组件视图位于packages/native/apple/Sources/Astryx/<ComponentRoot>/,其规格是docs/specs/components/<ComponentRoot>/<Name>.swift.spec.md。<Name>是核心组件的名称,<ComponentRoot>是核心存放组件的文件夹。该规格是一种component类别的知识记录,id 为component:<language>/<Name>,在platform_of中指定其核心组件,由docs/templates/knowledge/component-spec.md构建(architecture:knowledge-contractsINV27)。在核心组件有自己的记录之前,platform_of仍然指定component:<Name>,核心组件的公共源码和文档作为其契约。一个规格覆盖该语言中该组件在语言所服务的每个平台(Swift 服务于ios和macos)上的所有实现。适用于某语言所有组件的规则是packages/native/specs/<language>/下的架构记录,命名为<slug>.spec.md。合并后的原生组件规格描述该组件在该语言中的实现。它绝不改变核心契约,也绝不与spec:AST-082或本记录矛盾;若发生矛盾,以spec:AST-082和本记录为准。 - FR2 — 原生优先。 当平台自有的控件满足组件契约时,原生组件将使用该控件(
spec:AST-082/FR11)。在 Swift 中,这是 SwiftUI 控件;若 SwiftUI 没有,则是 UIKit 或 AppKit 控件。只有当平台没有可用控件时,组件才会自绘控件,并且其规格会说明它查找了哪个平台控件以及它为何不适用。 - FR3 — Apple 平台遵循 Apple 人机界面指南。 在
ios和macos上,呈现和交互遵循 Apple 人机界面指南:布局和间距约定、最小触摸目标、Dynamic Type、SF Symbols(spec:AST-082/FR17)、系统材质、动效(包括 Reduce Motion)、触觉反馈和 VoiceOver。每个规格都会说明它遵循的指南页面。核心契约保留组件的含义、文案、状态和无障碍语义;指南决定平台如何呈现它们,但按屏幕尺寸在呈现方式之间做选择时,使用spec:AST-012FR9 的 compact 定义,而不是 size classes。 - FR4 — 品牌在所有其他方面通过主题呈现。 FR2 和 FR3 未规定的部分,例如强调色和填充色、字体家族、边角形状、间距和图标选择,均来自应用的主题:来自
defineTheme定义(spec:AST-082/FR18)的令牌(tokens),以及来自defineNativeTheme(spec:AST-082/FR10)的原生意图和平台条目。组件从主题读取每一个此类值,绝不硬编码,也绝不为某个平台增加视觉 prop(spec:AST-082/DEC-2)。每个规格列出组件读取的主题值。 - FR5 — 每个原生组件都以相同方式进行测试和验证。 对原生组件的更改随附:
- 包测试目标中的单元测试,覆盖参数映射、默认值和状态变化,在包支持的每个平台上构建并运行;
- 参数的命名和类型符合平台为组件生成的契约(
spec:AST-082/FR5):每个平台都遵守的核心 props 加上该平台自己的 props(spec:AST-082/FR3),绝不单纯为了对齐而保留某个 prop,并且契约漂移测试通过,但 Current-state impact 中列出的临时 Swift 视图除外; - 对核心契约要求的标签、特征和值的无障碍断言,并在最大的 Dynamic Type 尺寸下进行一次检查;
- 检查组件是否能使用两个不同的主题渲染,且中间没有它自己的任何值;
- 从模拟器或设备捕获每个状态,包括浅色和深色模式以及最大文本尺寸,并随变更附带。原生优先、指南和品牌的主张都基于这些捕获,而非源码或样式值(
spec:AST-082/FR12)。无法被捕获的主张应报告为未测量。
- FR6 — 来自原生组的原生更改在规格审查后获得批准。 如果某个拉取请求的所有变更文件都在
packages/native/下,或是原生组件规格(docs/specs/components/**/<Name>.<language>.spec.md),并且其作者和每个提交作者都是原生组成员,那么只要满足以下三个条件,该请求即可由工程负责人基于其确切 head 批准,无需单独进行代码或设计审查:其必需检查通过;审查应用已审查过该确切 head 且未指出任何缺陷;对照spec:AST-082、本记录以及它所触及的每个组件的原生规格进行审查,认定它们定义的所有需求均已满足。规格定义的行为必须与规格一致,破坏此类需求的更改不会获得批准。尚无规格定义的行为不会阻止批准,如在 lab 包中那样:审查会将每个此类行为记录为规格缺口,以便后续补充规格。原生组是 GitHub 账号cixzhang、ejc3、ejhammond、ernestt、imdreamrunner和vjeux。更改上述路径之外的任何文件,或带有任何其他人提交的拉取请求,都遵循仓库的正常审查门禁。任何审查者的变更请求仍会阻止合并。更改原生组即是对本记录的更改。
平台支持¶
- 支持的功能/引擎下限:每个 Swift package 自行声明其平台和操作系统版本,直至
spec:AST-082/OQ4定案。 - 不支持的行为:比当前操作系统更新的能力按照
spec:AST-082/FR11的要求降级;组件永远不会渲染空白或损坏状态。 - 浏览器证据:无。原生声明由模拟器或设备上的捕获证明(FR5)。
当前状态影响¶
@astryxdesign/native将新增packages/native/specs/,每种语言一个目录,首先从swift/开始。该目录不会被发布。packages/native/specs/swift/下的 Swift specs 以及包模板packages/native/specs/TEMPLATE.md早于 FR1 的记录形式。它们将在一次变更中转换为知识记录,并移除该模板。在此之前,包的 README 仍会提及该模板,而新的组件 spec 则遵循 FR1。- 没有架构、家族、贡献或消费者文档记录的变更。
- 目前尚不存在原生组件 spec。
- 组件文件夹位于某种语言的实现包内。对于 Swift,该包是
packages/native/apple/,其Astryx产品包含 SwiftUI 视图。 Astryx产品中的首批 Swift 视图(Banner、Button、Card、Heading、Text 和 TextInput)使用手写参数,包括为契约的onClick提供的action,直到它们迁移到生成的契约。在此之前,它们是唯一豁免 FR5 的生成参数要求的原生组件;所有其他 FR5 检查仍然适用于它们。新的视图绝不享有此豁免。- Swift 测试以 Swift 包测试的形式运行;在 SwiftUI 中不暴露无障碍树,因此 FR5 的无障碍断言检查视图设置的标签(label)、特征(traits)和值(value),而不是 VoiceOver 读取的树。在存在由 app 托管的 iOS 测试目标之前,变更会将渲染树的无障碍报告为“未测量”,正如 FR5 会报告其无法捕获的声明一样。所有其他 FR5 检查仍然适用。
验证¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 |
|---|---|---|---|
| FR1 | 检查视图的文件夹以及核心组件 spec 旁该 spec 的路径,并对记录 frontmatter、id 和 platform_of 运行 pnpm check:knowledge |
每种语言一个 spec;一个没有核心契约的组件 spec;一个成员组件核心驻留在另一个组件的文件夹中 | 位于镜像核心组件根目录的文件夹之外的视图,位于 docs/specs/components/ 下核心组件文件夹之外、没有有效记录 frontmatter、使用另一个 id、未指明核心组件或重命名核心 prop 的组件 spec 会通过 |
| FR2 | spec 对其所基于的平台控件的说明,或为何没有合适的平台控件,以及状态捕获 | 基于平台控件构建的组件;没有平台控件的组件 | 组件在存在合适的平台控件时自行绘制控件,且其 spec 中未说明理由 |
| FR3 | spec 对其遵循的平台指南的说明,以及捕获内容 | 命中目标尺寸;最大 Dynamic Type;Reduce Motion;VoiceOver 焦点 | 捕获显示命中目标低于平台最小值,或文本不随动态类型缩放 |
| FR4 | 使用两种主题的主题测试,外加对字面量的源码审查 | 默认主题;第二种具有不同颜色、字体和形状的主题 | 品牌值在两种主题下保持不变,或添加了仅平台可见的视觉 prop |
| FR5 | 该包在每个受支持平台上的测试,以及随变更附带的截图 | 浅色;深色;最大文本字号;核心契约所命名的每个状态 | 一项变更在没有测试、没有截图的情况下合并,或仅以源代码为依据、基于截图的声明 |
| FR6 | 变更路径、提交作者、审查应用的 exact-head 审查、规范审查的发现,以及审批 | 小组成员提交的所有原生路径;某条规范定义的需求未满足;无规范定义的行为;docs/specs/components/ 下的原生组件规范;位于 packages/native/ 及这些规范之外的路径;来自他人的提交 |
未经 exact-head 审查应用验证或规范审查的审批;规范定义的需求未满足时的审批;未审查就批准的范围外拉取请求;仅因行为无规范定义而阻塞的范围内拉取请求 |
决策日志¶
DEC-1 — 平台惯例优先决定;主题填补它们未明确的内容¶
参考: spec:AST-093/DEC-1
决策者: cixzhang, 2026-10-23
在 iOS 或 macOS 上,用户期望控件的外观和行为与设备上的其余部分一致,因此平台自身的控件和 Apple Human Interface Guidelines 优先决定。应用的身份仍然重要,因此平台未明确的一切内容都来自应用已经为每个界面统一定义一次的主题。
已否决:逐像素匹配 Web 渲染,因为这会覆盖用户所依赖的平台惯例。
DEC-2 — 原生小组的原生变更在规范审查后合并¶
参考: spec:AST-093/DEC-2
决策者: cixzhang, 2026-10-23
@astryxdesign/native 仅发布到 canary 频道,因此没有稳定版用户会收到原生变更。在实验进行期间,开发它的人需要快速落地组件,因此原生变更无需等待单独的代码或设计审查。规范仍是契约:每项变更在批准前都会对照规范审查,若破坏某个规范定义的需求,该变更会被阻止。尚无规范覆盖的行为同样欢迎,就像 lab 包中那样,它会成为待弥补的规范缺口,而不是等待的理由。必需的检查、截图以及任何审查者提出的修改请求仍会保护该分支。
已否决:仅凭通过检查就批准,因为这会允许破坏规范的变更在未审查的情况下合并。
开放问题¶
- OQ1 — Android 和 Windows 上适用哪些指导方针?(
human-design) 每个平台的第一个原生组件在合并前都需要与 FR3 对应的要求。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx