Icon (Swift) 组件契约¶
契约一览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | Icon(_ icon: IconName, color: IconColor? = nil, size: IconSize? = nil, label: String? = nil) 和 Icon(_ props: IconProps),是模块 Astryx 中的一个 SwiftUI View。IconName 是一个以字符串为底层的名称,每个内置名称都是其静态成员(.search、.close)。 |
| 行为 | 绘制主题或平台将名称映射到的图像(SF Symbol,或应用随附的资源),放置在以 Dynamic Type 放大的核心图标尺寸的方形盒子中,并使用核心的图标颜色 token 或周围环境的前景色。没有映射的名称,或应用未随附的资源,不绘制任何内容。 |
| 终端用户影响 | 用户为每个共享图标看到平台自身的符号,或在其主题映射了对应图标时看到应用自身的图形,尺寸和颜色与 Web 端一致;VoiceOver 只朗读带有 label 的图标。 |
| 构建者影响 | 应用传入共享名称(.search)或其在主题中映射的名称("acme:rocket")。Web 端也接受的 SVG 组件没有 Swift 形式。 |
| 兼容性/就绪状态 | 增量式:一个新视图和一个新生成的 IconName 类型。草案;已在 macOS 和 iOS Simulator 上构建并测试;设备截图已附于变更中。 |
| 审查检查 | 拒绝以下情形:为未知名称提供替代符号、图标槽位采用图像或属性文本形式、包含超出契约的视觉参数、VoiceOver 朗读无标签图标,或拥有者的尺寸优先于显式 size。 |
| 管辖规则 | spec:AST-082 中的 FR4、FR7、FR17;spec:AST-093 中的 FR1–FR5;packages/native/specs/swift/library/ 下的 Swift 组件 API、样式、槽位、主题环境和无障碍记录。 |
此表是审查投影;下文正文具有权威性。
意图¶
在 Apple 平台上,Icon 将 Astryx 的共享图标名称绘制为 SF Symbols;若主题映射了图标,则绘制为应用随附的图像。因此,系统控件旁边的图标看起来像平台自身的图标,同时其尺寸、颜色和无障碍特性遵循核心 Icon 契约。
兼容性与迁移¶
- 已发布默认值保留:
not yet released - 兼容性类别:增量式
- 受控/非受控行为:不适用
- 迁移决策:无
使用方的迁移说明应写入使用方文档和发布说明。
所有权边界¶
拥有
- 将共享图标名称解析为图像:主题的映射(SF Symbol 或应用资源),否则使用平台的默认 SF Symbol。
- 在以 Dynamic Type 放大的核心图标尺寸的方形盒子中绘制图像,使用核心的图标颜色 token。当资源目录将资源渲染为模板图像(template image)时,该资源采用颜色 token;当渲染为原始图像(original image)时,该资源保留自身颜色。
- 图标的 VoiceOver 暴露程度。
不拥有 / 非目标
icon、color、size和label的含义及内置名称——由component:Icon和spec:AST-082FR17 拥有。- 拥有者为其图标槽位中的图标指定的大小——由每个拥有该槽位的组件和
architecture:component-size-cascade拥有。 - 每个名称的默认 SF Symbol——由
@astryxdesign/native的图标默认值拥有,测试会保持其与 Swift 映射一致。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 拥有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 图标名称 | 内置名称;主题映射的 <library>:<name> |
IconName,底层为字符串,在线上传输中亦为字符串,每个内置名称都是其静态成员 |
始终 | 必填 | component:Icon |
实验性 | 未映射的名称会阻止开发构建,并在发布版本中不绘制任何内容 |
| 符号来源 | 主题映射;平台默认值 | Theme(icons:) 使用 SF Symbol 或应用资源替换内置名称,或注册库名称 |
始终 | 平台默认值 | component:swift/Icon |
实验性 | 主题条目优先于默认值 |
| size | xsm、sm、md、lg;未设置 |
在默认文本尺寸下为 12、16、20、24 点 | 始终 | 所有者的图标尺寸,否则为 md |
component:Icon |
实验性 | 未设置时采用所有者的尺寸,然后为 md |
| color | primary、secondary、tertiary、disabled、accent、info、success、error、warning、inherit;未设置 |
core 的图标颜色令牌;inherit 保持周围的前景样式 |
始终 | inherit |
component:Icon |
实验性 | 未设置时为 inherit |
行为与布局契约¶
| ID | 候选不变量 | 依据 | 草稿审查状态 |
|---|---|---|---|
| FR1 | 视图 MUST 绘制主题的 icons 将名称映射到的图像,即 SF Symbol 或应用随附的资产;否则使用内置名称的平台默认符号。如果某个名称未映射,或应用未随附某个资产,MUST 在开发构建中停止构建并用一条消息指明该名称,在发布构建中不绘制任何内容,绝不使用替代物。 |
spec:AST-082 FR17;Swift slots S2 |
待验证 |
| FR2 | 符号 MUST 适配一个正方形框,其边长为 core 以点计的尺寸(xsm、sm、md、lg 分别为 12、16、20、24),再乘以主题环境读取的 Dynamic Type 缩放比例。 |
core Icon 尺寸;spec:AST-093 FR3;theme environment E1 |
待验证 |
| FR3 | 视图 MUST 使用自身的 size,否则使用其所属组件在文档化的图标插槽中提供给图标的尺寸,否则使用 md。 |
architecture:component-size-cascade;Swift slots S4 |
待验证 |
| FR4 | 视图 MUST 以 core 的令牌绘制其 color —— 主要和次要图标令牌、tertiary 对应的次要图标令牌、禁用图标令牌、强调色,以及 info、success、error、warning 状态图标角色;对于 inherit 或无颜色,MUST 保持周围的前景样式。 |
core Icon 颜色映射;spec:AST-093 FR4 |
待验证 |
| FR5 | 两个初始化器 MUST 构建相同的 IconProps;带标签的初始化器接受契约的 props,并带有生成的类型和默认值;基础 props(id、isHidden)通过 IconProps 传入。当 isHidden 为真时,视图不绘制任何内容;id 成为无障碍标识符。 |
Swift component API A2, A3, A7;spec:AST-082 FR7 |
待验证 |
允许的变化¶
- AV1 — 字形形状。 字形是平台的 SF Symbol,而非 Web 的 SVG;主题可以将任何名称映射到另一个 SF Symbol 或应用随附的图像(
spec:AST-082FR17)。
代表性状态¶
| 状态 | 必需不变量 | 允许的变化 |
|---|---|---|
| 每种尺寸 | 在 Large 文本下方框边长为 12、16、20、24 点 | 每个符号的字形比例 |
| 每种颜色,浅色与深色 | 当前模式下该颜色的令牌 | 无 |
| 在所属组件的图标插槽内 | 使用所有者的尺寸,除非图标自行设置 | 无 |
| 最大文本尺寸 | 方框随 Dynamic Type 增长 | 无 |
| 带标签与不带标签 | VoiceOver 只读取带标签的图标 | 无 |
变换与优先级顺序¶
- ORD1 — 图像。 主题映射(SF Symbol 或应用资产)→ 平台默认 SF Symbol → 无。
- ORD2 — 尺寸。 显式
size→ 所有者图标尺寸 →md,然后 × Dynamic Type 缩放比例。
性能与资源¶
- PR1 — 不持有自身图像数据。 视图按名称绘制系统符号,或按名称绘制应用主 bundle 中的资产;它不持有任何图像数据,也不从网络加载任何内容。
无障碍契约¶
- AR1 — 除非有标签,否则视为装饰性元素。 当没有
label,或label为空时,该视图对 VoiceOver 隐藏。有标签时,它是一个由该标签命名的图像元素,保留 SwiftUI 的图像特征,且不添加任何其他特征(spec:AST-082FR17;Swift accessibility X1、X4)。在头像的状态槽中,带标签的图标还会命名该状态,并与头像名称合并(component:swift/AvatarAR6)。 - AR2 — 不测量渲染后的无障碍树。 测试断言视图所设置的内容;在存在由应用托管的测试目标之前,不测量渲染后的无障碍树。
设计关系¶
| 构成或状态 | 设计要求 | 呈现权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 字形 | SF Symbols(Apple Human Interface Guidelines),或应用资源 | 由平台规定 | 辅助 | FR1, FR2 |
组件落实设计要求,但不照搬其设计依据。
平台控件:SwiftUI Image(systemName:),或用于应用资源的 Image(_:bundle:)。它是平台自身的图标视图,满足契约,因此无需自定义绘制(spec:AST-093 FR2)。指南页面:Apple Human Interface Guidelines 中的 SF Symbols 与 Accessibility。
读取的主题值:color.iconPrimary、color.iconSecondary、color.iconDisabled、color.accent、color.iconInfo、color.iconSuccess、color.iconError、color.iconWarning、主题的 icons 映射,以及 Dynamic Type 缩放。
家族与系统关系¶
component:Icon拥有 props、内置名称、尺寸缩放和颜色映射;本记录仅说明 Swift 如何绘制它们。architecture:component-size-cascade负责确定所有者图标尺寸生效的时机;所有者通过本视图读取的内部环境值来设置它。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1 | IconTests.swift 符号与资源测试(测试包代替应用的资源包);contracts.test.ts 的 IconName 测试 |
每个内置符号;主题替换;库名称;随附资源;缺失资源不绘制任何内容并被报告(release 构建路径) | 缺失默认项、平台缺少该符号、缺失资源仍绘制或未被上报,或替代项失败,则测试失败 | audit:swift/Icon/symbols |
| FR2, FR3 | IconTests.swift 的尺寸与 Dynamic Type 渲染 |
每种尺寸;所有者尺寸;显式尺寸;AX5 | 错误的边长,或所有者尺寸覆盖显式尺寸,则测试失败 | audit:swift/Icon/size |
| FR4 | IconTests.swift 的颜色映射与双主题渲染 |
每种颜色;neutral 与 butter | 错误的 token,或使用视图自身的颜色,则测试失败 | audit:swift/Icon/color |
| FR5 | IconTests.swift 的初始化器与隐藏测试 |
两种初始化器;isHidden |
props 不同,或隐藏图标仍被绘制,则测试失败 | audit:swift/Icon/api |
| AR1 | IconTests.swift 的无障碍断言 |
带标签、无标签、空标签 | 无标签图标被添加了标签,或带标签图标缺少标签,则测试失败 | audit:swift/Icon/a11y |
决策日志¶
未记录任何组件本地决策。
未决问题¶
无。
内容边界¶
本文件不重复消费方 prop 表/示例、当前审计结果、实现步骤或家族/系统规则。它链接到这些内容的拥有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx