Button (Swift) 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公开契约 | Button(label:variant:size:elevation:isLoading:isInterruptible:isDisabled:width:tooltip:href:base:onClick:) 和 Button(_ props: ButtonProps),是模块 Astryx 中的一个 SwiftUI View。 |
| 行为 | 使用 Astryx 按钮样式绘制的 SwiftUI Button;或者,当启用的 Button 带有 href 时,则是一个 SwiftUI Link。加载时,spinner 会覆盖标签,标签位置保持不变;除非按钮可中断,否则按压会等待。在 iOS 和 iPadOS 26 及更高版本中,在系统栏内或使用浮动玻璃(floating-glass)选项时,它用系统的 Liquid Glass 取代自身的填充:未设置的 variant 与 core 中一样是 secondary,并且每个 variant 在玻璃效果下都保持其含义。 |
| 最终用户影响 | 使用者获得一个操作控件,其宽度在加载时保持不变,并且不会因意外而运行两次;链接型 Button 在忙碌时仍然保持链接,因此 VoiceOver 和键盘焦点会停留在它上面。在栏和浮动控件中,它的外观和行为与旁边的系统按钮保持一致:是单层玻璃,而不是玻璃内部的填充;主要或破坏性操作依然一眼可辨。 |
| 构建者影响 | 应用传入 core 的 Button props;href 让同一个视图通过系统打开目标地址。在栏中的 Button 无需额外代码;在浮动容器上调用 .astryxFloating() 可让其内的 Button 采用玻璃效果。调用点设置的 variant 始终有效。 |
| 兼容性/就绪状态 | 对 canary 调用者为破坏性变更:action:、fillsWidth:、icon: 以及手写的 AstryxButtonVariant 和 AstryxButtonSize 让位于生成的 ButtonProps(onClick:、width:、ButtonVariant、ButtonSize)。草稿;已在 macOS 和 iOS Simulator 上构建并测试。 |
| 审查检查 | 应拒绝以下情况:加载中的链接切换成按钮;加载中的 Button 在不可中断时运行 onClick 或打开其链接;加载期间尺寸变化;或带 href 的 disabled Button 被打开。还应拒绝在栏的玻璃内部绘制 Astryx 填充、玻璃效果覆盖或丢弃已设置的 variant、在减弱透明度或增强对比度下绘制玻璃,以及未通过模拟器截图门禁就合并玻璃效果更改。 |
| 约束规则 | component:Button FR7–FR11;spec:AST-082 FR3;spec:AST-093 FR1–FR5;packages/native/specs/swift/library/ 下的 Swift 组件 API 记录(A2–A5);以及下方的 DEC-1。 |
此表是审查时的概览;以下正文具有权威性。
意图¶
在 Apple 平台上,Button 是 core 的操作控件,使用 SwiftUI 自带的 button 和 link 绘制,因此按压、焦点和 VoiceOver 都按平台方式工作,同时其外观、加载和链接行为遵循 core 的 Button 契约。
兼容性与迁移¶
- 保留的发布默认值:
not yet released - 兼容性类别:对 canary 调用者为破坏性变更(手写参数 → 生成的
ButtonProps) - 受控/非受控行为:不适用
- 迁移决策:无
消费者迁移说明应放在消费者文档和发布说明中。
所有权边界¶
拥有
- Swift 如何绘制 core 的 Button:所使用的 SwiftUI 控件、加载表现、按压何时生效,以及
href何时使其成为链接。 - Button 如何在 Apple 平台上与系统的 Liquid Glass 保持一致:在系统栏中、在浮动玻璃(floating-glass)选项下,以及在减弱透明度或增强对比度状态下(FR7–FR11)。
不拥有 / 非目标
- Button 的 props 含义、其 variants 和 sizes,以及 pending 和 disabled 状态——由
component:Button拥有。 - 链接可以打开哪些目标地址——由
family:navigation-destinations拥有。 - 一般情况下,prop 如何切换到不同的 SwiftUI 控件——由 Swift 组件 API 记录(A2)拥有。
- 玻璃效果本身、栏如何对其项目分组,以及滚动边缘效果——由系统拥有。
- 导航上下文中的搜索——不是 Button 关注的问题。
- macOS 工具栏和浮动控件——FR7–FR10 涵盖 iOS 和 iPadOS 26;在 macOS 上保持 token 外观(FR10)。
公共概念¶
| 概念 | 闭合值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| control | button; link | 启用 href 时为 SwiftUI Link,否则为 SwiftUI Button |
始终 | button | component:swift/Button |
experimental | 不是 URL 的 href 会使其保持为 button |
| loading | idle; loading | isLoading:在标签上方显示加载指示器,按下操作会等待 |
始终 | idle | component:Button |
experimental | 无 |
| interruptible | off; on | isInterruptible:加载期间按下操作和链接打开仍会生效 |
加载期间 | off | component:Button |
experimental | 无 |
| availability | operable; busy-only; disabled | disabled 优先于 loading | 始终 | operable | component:Button |
experimental | 无 |
| surface | token; bar glass; floating glass; solid | Button 所在位置决定其标签背后绘制什么(FR7–FR10) | 玻璃类值仅在 iOS 和 iPadOS 26 及更高版本可用 | token | component:swift/Button |
experimental | 无 |
行为与布局契约¶
| ID | 候选不变量 | 依据 | 草案审查状态 |
|---|---|---|---|
| FR1 | 两个初始化器 MUST 构建相同的 ButtonProps;基础属性(id、isHidden)通过 ButtonProps 提供。 |
Swift component API A2, A3 | verify |
| FR2 | 加载期间,视图 MUST 在标签上方绘制加载指示器,保持标签的位置不变以使其尺寸不变,保持完全不透明,并向 VoiceOver 读作忙碌状态(core 的目录消息为 "Loading")。除非它是 interruptible 的,否则加载期间 MUST NOT 运行 onClick;interruptible 的加载 Button 会在每次按下时运行 onClick。 |
component:Button FR7–FR9 |
verify |
| FR3 | 带有 href 的启用 Button MUST 以 Astryx 按钮样式绘制一个指向该目标的 SwiftUI Link,VoiceOver 将其读作链接。带有 href 的禁用 Button MUST 绘制其禁用按钮,且该按钮永远不会打开。 |
component:Button FR11;spec:AST-082 FR3 |
verify |
| FR4 | 带有 href 的加载中 Button MUST 保持为 Link:它保持焦点、显示加载指示器、被读作忙碌状态,并且在加载结束前不会打开其目标地址,除非该 Button 可中断,在这种情况下每次激活都会打开它。它绝不会在忙碌时切换为按钮。 |
component:Button FR9(“链接模式的 Button 在仅忙碌时保持为链接”)、FR11 |
待验证 |
| FR5 | 如果 Button 的 href 是脚本 URL(javascript:、vbscript:)或 data: URL 中的 HTML 文档,那么在 core 规范化后(移除控制字符、去除首尾空白、以小写形式比较 scheme,且冒号后不带空格),它 MUST NOT 打开该 URL:它绘制启用状态的按钮,该按钮运行 onClick,且外观不像禁用状态。 |
component:Button FR11;family:navigation-destinations |
待验证 |
| FR6 | 禁用的 Button MUST 保留其键盘焦点停留点,并在获得焦点时显示工具提示、绘制禁用外观、在 VoiceOver 中被读作变暗的按钮,且永不运行 onClick;已聚焦的 Button 在变为禁用时会保持单一视图结构及其焦点。带有 href 的 Button 将 Link 与禁用的按钮保留在同一结构中;变为禁用时,焦点从链接移到按钮;重新启用时,焦点移回链接,因此焦点始终留在组件内。 |
component:Button FR10;family:buttons FR3 |
待验证 |
| FR7 | 在 iOS 和 iPadOS 26 及更高版本中,位于系统栏(导航栏或工具栏)中的 Button MUST 不绘制自身的填充或边框,因此该栏的玻璃是它唯一的装饰(已设置的 elevation 仍会绘制其阴影,FR11);其标签和任何色调都遵循 FR8。未设置的 variant 为 secondary,与 core 中一致,因此它绘制 secondary 的栏处理方式:仅标签,使用 color.textPrimary,位于该栏的玻璃上。这不需要新增 prop 或 modifier。 |
DEC-1;Apple 的 Liquid Glass 指南(移除系统栏中的自定义背景) | 待验证 |
| FR8 | 调用点所设置的 variant MUST 始终得到遵守。在 iOS 和 iPadOS 26 及更高版本中,在系统栏内以及浮动选择加入机制(FR9)下,它映射到最能保留其语义的玻璃处理方式,且绝不会使用另一种 variant 的处理方式来绘制(在系统栏中,secondary 和 ghost 共享该栏的玻璃):primary → 突出玻璃,着色为 color.accent,标签颜色 color.onAccent;destructive → 突出玻璃,着色为 color.error,标签颜色 color.onError;secondary → 常规玻璃(在系统栏中即该栏自身的玻璃),标签颜色 color.textPrimary,无 color.neutral 填充;ghost → 浮动:透明玻璃,标签颜色 color.textPrimary;在系统栏中:该栏自身的玻璃,标签颜色 color.textPrimary(该栏负责其各项的背景)。 |
DEC-1 | 待验证 |
| FR9 | 在 iOS 和 iPadOS 26 及更高版本中,Apple 专属 modifier .astryxFloating() MUST 仅将容器标记为浮动(位于滚动内容上方的控件);其中的 Button 绘制 FR8 的浮动处理方式,并受主题的 material(ORD2)和 FR10 约束,未设置的 variant 绘制为 secondary。没有该 modifier 时,系统栏之外的 Button 保持其 token 外观。该 modifier 不是 prop,也不会改变任何 ButtonProps(Swift 组件 API A2)。 |
DEC-1;Swift 组件 API A1c(modifier 的 astryx 前缀) |
待验证 |
| FR10 | 在开启“降低透明度”或“增强对比度”时,一个本会绘制玻璃(FR7–FR9)的 Button MUST 不绘制任何玻璃:其变体的 token 填充(primary 对应 color.accent,destructive 对应 color.error,secondary 和未设置的 variant 对应 color.neutral,ghost 对应 color.backgroundSurface)带 color.borderEmphasized 边缘,使其标签保持实心、可见的背景。在 FR7–FR9 未覆盖的 iOS 26 之前版本以及 macOS 上,token 外观保持不变。 |
DEC-1; spec:AST-093 FR2 |
待验证 |
| FR11 | 在玻璃中,每个 prop 都保留核心语义:isLoading、isInterruptible、isDisabled、href 和 tooltip 的行为与 FR2–FR6 一致;size 设置控件的最小高度和标签类型(component:Button FR4);显式设置的 width 会被应用,但上限为栏或容器可提供的空间(component:Button FR5);elevation 将阴影绘制在玻璃下方(component:Button FR13)。在容量足够的栏中,Button 的标签 MUST NOT 被 Astryx 的内边距截断。 |
component:Button FR4、FR5、FR7–FR11、FR13;DEC-1 |
待验证 |
玻璃中的变体映射¶
FR7–FR9 汇总在一张表中。“最不令人意外”意味着调用点获得其 variant 原本就承诺的效果,并以系统玻璃作为其表面。
variant |
在系统栏中(iOS 和 iPadOS 26) | 浮动并已选用(iOS 和 iPadOS 26) | 最不令人意外的原因 |
|---|---|---|---|
| not set | 同 secondary:栏的玻璃,标签 color.textPrimary,无填充 |
常规玻璃,标签 color.textPrimary(同 secondary) |
核心的默认值是 secondary,因此未设置的 Button 在每个平台上都是 secondary 按钮 |
primary |
醒目的玻璃,以 color.accent 着色,标签 color.onAccent |
相同 | 仍然是那个带填充、accent 色的主要操作,正如系统栏中醒目的按钮那样 |
secondary |
栏的玻璃,标签 color.textPrimary,无 color.neutral 填充 |
常规玻璃,标签 color.textPrimary |
仍然是中性操作;玻璃取代了中性填充,因此只有一个表面,而不是两个 |
ghost |
栏的玻璃,标签 color.textPrimary(栏负责其各项的背景) |
透明玻璃,标签 color.textPrimary |
仍然是最安静的操作;透明玻璃是让标签在动态内容上保持可读的最不显眼的表面 |
destructive |
醒目的玻璃,以 color.error 着色,标签 color.onError |
相同 | 按下之前仍呈现为 destructive 操作 |
允许的变体¶
- AV1 — 平台控件。 该控件是 SwiftUI 的
Button或Link,因此焦点环、按下反馈以及系统打开目标地址的方式均由平台自身决定。 - AV2 — 系统玻璃。 在玻璃(FR7–FR9)中,折射、栏如何对其项目进行分组和变形、按下效果以及滚动边缘效果均属于系统行为,并可能随每个 iOS 版本而变化。
代表性状态¶
| 状态 | 必需不变式 | 允许的变体 |
|---|---|---|
| loading | 尺寸与 idle 相同;显示 spinner;忙碌;按下时等待 | spinner 为系统自带 |
| loading 且可中断 | 按下能生效 | 无 |
设置了 href 且启用 |
渲染为 Link |
无 |
设置了 href 且禁用 |
渲染为变暗的按钮,且永不打开 | 无 |
设置了 href 且 loading |
渲染为 Link,在加载结束前不会打开 |
无 |
在 bar 中,variant 未设置 |
secondary 的 bar 处理;无 Astryx 填充 |
系统的玻璃与分组效果 |
在 bar 中,variant 已设置 |
FR8 对该 variant 的处理 | 系统的玻璃与分组效果 |
| 浮动且已选择启用 | FR8 的处理;未设置时采用 secondary 的处理 |
系统的玻璃效果 |
| Reduce Transparency 或 Increase Contrast | 使用带边缘的实色 token 填充,不使用玻璃 | 无 |
转换与优先级顺序¶
- ORD1 — 可用性。 先禁用,再 loading(仅忙碌,除非可中断),然后才可操作,与核心一致。
- ORD2 — 表面。 先应用 Reduce Transparency 或 Increase Contrast(实色,FR10);再应用主题的
material(spec:AST-082FR10):opaque会在浮动玻璃(FR9)原本绘制的位置绘制 FR10 的实色表面,而 bar 中的 Button 仍不绘制自身填充;translucent、ios条目中的liquidGlass或缺失的material则保持 FR7–FR9;随后应用variant的处理(FR8,未设置的variant视为secondary);最后在 bar 和浮动容器之外应用 token 外观。 放置(Placement)绝不会覆盖已设置的variant。
性能与资源¶
- PR1 — 空闲时不做任何工作。 视图不持有计时器或任务;loading 是由调用方设置的 prop。
无障碍契约¶
- AR1 — 名称与状态。 标签在每个状态下都命名该控件;loading 的 Button 会将核心的“Loading”消息作为其值,并在 loading 开始时进行播报。Link Button 读作链接,禁用 Button 读作变暗。
- AR3 — 玻璃保留名称与角色。 在玻璃中,Button 保留其标签、按钮或链接角色,以及其 loading 和禁用状态(AR1);系统只绘制标签背后的内容。
- AR2 — 不测量渲染出的无障碍树。 测试断言的是视图所设置的内容;在存在由应用托管的测试目标之前,不测量渲染出的无障碍树。
设计关系¶
| 解剖结构或状态 | 设计要求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| Spinner | 系统的活动指示器 | 由平台规定 | 辅助 | FR2、FR4 |
| 玻璃表面 | 系统的 Liquid Glass(常规、清晰、突出) | 由平台规定 | 辅助 | FR7–FR10 |
该组件实现设计要求,但不再复述其设计理由。
平台控件:SwiftUI Button 和 Link(配合 ProgressView);它们是平台自带的控件,并满足契约(spec:AST-093 FR2)。tooltip 通过共享的 Astryx tooltip(library/tooltip.spec.md)显示。指南页面:Apple Human Interface Guidelines 中的 Buttons、Progress indicators、Materials (Liquid Glass)、Toolbars 和 Accessibility (Reduce Transparency, Increase Contrast)(spec:AST-093 FR3)。
读取的主题值(spec:AST-093 FR4):color.accent、color.onAccent、
color.error、color.onError、color.neutral、color.textPrimary、
color.backgroundSurface 和 color.borderEmphasized(实色回退)、
原生主题的 material 意图,包括 ios 条目中的 material
(spec:AST-082 FR10;ORD2)、
size.elementSm、size.elementMd、size.elementLg、radius.element、
space 的 padding 步进、font.label 和 font.family.body、
shadow.low、shadow.med、shadow.high 各层级,以及 Dynamic Type
缩放。
家族与系统关系¶
component:Button拥有 props、pending 和 disabled 状态以及链接模式;本记录只说明 Swift 如何绘制它们。family:navigation-destinations负责链接的目标处理。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1 | 加载中的 Button 显示系统 spinner、保持尺寸 且按下后什么都不做。 | loading;loading 且可中断 | 若按下在 loading 期间生效、尺寸变化 或 spinner 非系统提供,则失败。 | 组件、无障碍、平台 |
| FR4 | loading 按钮通过系统无障碍 API 在加载开始时播报“Loading”。 | loading | 若 i0S 或 macOS 在适配上未读出新值,则失败。 | 无障碍 |
| FR12 | 链接按钮可聚焦且以链接形式操作。按钮 不可聚焦且以按钮形式操作。 | 设置了 href 且启用;设置了 href 且禁用;设置了 href 且 loading |
若链接不可聚焦或不可由键盘 打开,则失败。 | 组件、无障碍 |
| FR11 | 禁用按钮永远不会打开,且变暗。 | 设置了 href 且禁用 |
若禁用按钮被激活并尝试打开,或未变暗,则失败。 | 组件、样式 |
| FR6 | 宽高比(elementSm、元素 md、元素 lg)> 4 像素字体 高度。最小目标尺寸符合 WCAG 2.2。 | 所有状态 | 若计算出的目标小于平台 最小尺寸,则失败。 | 组件、无障碍 |
| FR9 | 玻璃仅在浮动且明示选择启用时绘制, 且实色回退存在。 | 浮动且已选择启用;Reduce Transparency;Increase Contrast | 若玻璃出现在非浮动上下文、 在 Reduce Transparency 下绘制,或回退 缺失或不可访问,则失败。 | 组件、样式、无障碍 |
| FR7 | bar 按钮在 bar 高度内居中, 使用 bar 的玻璃分组处理,且不绘制 Astryx 填充。 | 在 bar 中,variant 未设置;在 bar 中,variant 已设置 |
若按钮绘制自己的填充,或未与 同组对齐,则失败。 | 组件、样式 |
| FR8 | 未设置 variant 的浮动按钮后退为 secondary; 已设置 variant 的浮动、bar 和普通按钮绘制该变体。 |
浮动且已选择启用;浮动;在 bar 中,variant 未设置;在 bar 中,variant 已设置 |
若普通按钮未绘制变体,或浮动 后退未使用 secondary,则失败。 |
组件、样式 |
| AR1 | 标签始终命名该控件,loading 播报“Loading”。 | loading;设置了 href 且启用;设置了 href 且 loading |
若自动化测试未在任何 状态中看到名称,则失败。 | 无障碍 |
| PR1 | 按钮运行时无计时器或后台任务。 | 无状态可检查:Button 更新为 loading 的值是组件内部的 | 若判断(不给调用方 prop) 运行计时器,则失败。 | 组件 |
| FR1 | ButtonTests.swift 初始化器测试 |
两个初始化器 | 属性不同则失败 | audit:swift/Button/api |
| FR2 | ButtonTests.swift 加载、宽度和可中断测试 |
加载中;加载中且可中断 | 加载中按下、尺寸变化或变暗则失败 | audit:swift/Button/loading |
| FR3 | ButtonTests.swift href 测试 |
启用和禁用状态且带 href |
禁用状态的 Button 打开链接,或启用状态的 Button 不是链接,则失败 | audit:swift/Button/link |
| FR4 | ButtonTests.swift 加载状态下,以及加载且可中断状态下的 href 测试 |
带 href 的加载中;可中断 |
忙碌中的链接变为按钮,或在加载结束前打开,则失败 | audit:swift/Button/link |
| FR5 | ButtonTests.swift 拒绝目标与规范化测试 |
javascript:、vbscript:、data:text/html、带填充的、混合大小写的、带控制字符的,以及 data: text/html;仍能打开的 data:image 和 mailto: |
被拒绝的目标被打开、未规范化的目标漏过,或被拒绝的目标显示为禁用,则失败 | audit:swift/Button/link |
| FR6 | ButtonTests.swift 禁用状态测试,包括带 href 的禁用 Button 在一种结构中保留其目标;焦点停止和焦点移动在应用托管的测试能够观察到它们之前不予测量 |
带和不带工具提示的禁用状态;带 href 的禁用状态 |
禁用 Button 执行 onClick 或打开其链接,或被标记为没有焦点停止,则失败 |
audit:swift/Button/disabled |
| AR1 | ButtonTests.swift 无障碍断言 |
空闲;加载中;链接 | 缺少名称、值或通告则失败 | audit:swift/Button/a11y |
| FR7 | 模拟器捕获门禁:在每个新版 iOS 上,浅色和深色模式下,导航栏和底部工具栏中放置未设置样式的 Button;一个单元测试断言栏内 Button 不绘制填充。证据缺口:SwiftUI 没有公开信号表明某个视图位于栏中,因此底部工具栏在检测通过该门禁之前仍未被验证 | 导航栏;底部工具栏 | 栏的玻璃内部出现 Astryx 填充则失败 | audit:swift/Button/glass |
| FR8 | Simulator 捕获门:栏中和浮动状态下、浅色与深色中的每个变体;以及变体到处理方式映射的单元测试 | primary; secondary; ghost; destructive | 使用另一种变体的处理方式绘制已设置的变体会失败,但在栏中 secondary 和 ghost 共享栏玻璃时除外 |
audit:swift/Button/glass |
| FR9 | Simulator 捕获门:带修饰符和不带修饰符的浮动 Button;以及修饰符不改变任何 ButtonProps 的单元测试 |
已选择;未选择 | 没有修饰符却绘制玻璃,或带修饰符却使用 token 填充,则失败 | audit:swift/Button/glass |
| FR10 | 开启 Reduce Transparency 和 Increase Contrast 时的 Simulator 捕获门 | 栏中和浮动中的每个变体 | 绘制了任何玻璃,或标签没有实色背景,则失败 | audit:swift/Button/glass |
| FR11 | ButtonTests.swift 中的加载和禁用测试;用于栏中和浮动状态下标签截断、size、width 和 elevation 的 Simulator 捕获门 |
加载中;禁用;长标签;每种 size;填充宽度;每种 elevation | 标签在有空间时被截断、加载或禁用状态丢失,或 core 会遵循但玻璃中会丢弃的 size、width、elevation,则失败 |
audit:swift/Button/glass |
决策日志¶
DEC-1 — Button 遵循系统的玻璃效果,且已设置的变体始终被遵循¶
参考: component:swift/Button/DEC-1
决策者: cixzhang, 2026-10-31
在 iOS 和 iPadOS 26 及更高版本中,系统栏中的 Button 不绘制自身的填充,因此栏的玻璃是其唯一的装饰;位于 Apple 专属修饰符标记为浮动的容器中的 Button 会绘制 SwiftUI 的玻璃;而 Reduce Transparency 或 Increase Contrast 会绘制实色 token 表面。调用点设置的 variant 在玻璃中保持其含义(FR8):primary 和 destructive 仍然是唯一的填充、彩色操作,secondary 和 ghost 保持中性。未设置的 variant 是 secondary,正如 core 所定义,因此未设置的栏 Button 具有中性标签,而原生栏项目会采用 tint。
已拒绝:不提供 Astryx 玻璃,应用在栏和浮动控件中使用 SwiftUI 自己的按钮。
未决问题¶
无。
内容边界¶
本文件不重复使用方 prop 表/示例、当前审计结果、实现步骤或组件族/系统规则。它链接到其所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx