跳转至

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-082 FR17 拥有。
  • 拥有者为其图标槽位中的图标指定的大小——由每个拥有该槽位的组件和 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-082 FR17)。

代表性状态

状态 必需不变量 允许的变化
每种尺寸 在 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-082 FR17;Swift accessibility X1、X4)。在头像的状态槽中,带标签的图标还会命名该状态,并与头像名称合并(component:swift/Avatar AR6)。
  • 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