AvatarStatusDot (Swift) 组件契约¶
契约一览¶
| 方面 | 契约 |
|---|---|
| 公共契约 | AvatarStatusDot(variant: AvatarStatusDotVariant? = nil, label: String? = nil) 和 AvatarStatusDot(_ props: AvatarStatusDotProps),一种 SwiftUI View,放置在 Avatar 的 status 插槽中。 |
| 行为 | 按其头像尺寸对应的层级绘制 core 的圆点:success 为实心,neutral 为圆环,error 为减号横条;每种样式均使用主题 token,并带表面边框。其标签并入头像的名称。 |
| 最终用户影响 | 用户不仅通过颜色,还通过形状识别谁在线、离开或忙碌;VoiceOver 会连同人名一起朗读该状态(“Ada Lovelace, Online”)。 |
| 构建者影响 | 应用可将圆点连同标签放入头像的尾随闭包中。圆点内部的自定义图标没有对应的 Swift 形式。 |
| 兼容性/就绪状态 | 增量式:新增视图、生成的 AvatarStatusDotProps,以及 Swift 字符串目录中 core 的“名称+状态”消息。草稿;已在 macOS 和 iOS 模拟器上构建并测试;已附设备截图。 |
| 评审检查项 | 若出现仅以颜色区分的状态、会调整头像大小或位置的圆点、VoiceOver 在头像内部单独朗读的圆点,或非主题 token 的颜色,均应拒绝。 |
| 治理规则 | spec:AST-082 FR4、FR7;spec:AST-093 FR1–FR5;位于 packages/native/specs/swift/library/ 下的 Swift 组件 API、插槽(S4)、主题环境和无障碍(X1、X6)记录。 |
此表为评审投影;下文正文为准。
意图¶
AvatarStatusDot 在 Apple 平台上通过形状和颜色展示头像上的状态,大小根据头像确定,并为头像提供其文字。
兼容性与迁移¶
- 已发布默认值保持不变:
not yet released - 兼容性类别:增量式
- 受控/非受控行为:不适用
- 迁移决策:无
消费者迁移说明应放入消费者文档和发布说明中。
所有权边界¶
拥有
- 圆点在不同变体下的尺寸层级、填充、边框和形状字形。
- 将其标签报告给持有它的头像。
不拥有 / 非目标
- 圆点的位置以及名称的组成方式——由
component:swift/Avatar拥有(FR7、AR6)。 - 变体的含义——由
component:AvatarStatusDot拥有。
公共概念¶
| 概念 | 封闭取值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效取值行为 |
|---|---|---|---|---|---|---|---|
| variant | success, neutral, error |
实心圆点、圆环、减号横条 | 始终 | success |
component:AvatarStatusDot |
实验性 | 无 |
| tier | small, medium, large | 10、20、32 磅圆点,分别对应不超过 36、72 以及更大的头像 | 由头像决定;单独存在时为 small | small | component:AvatarStatusDot |
实验性 | 无 |
行为与布局契约¶
| ID | 候选不变式 | 依据 | 草稿评审状态 |
|---|---|---|---|
| FR1 | 圆点 MUST 根据其头像的边长采用 core 的尺寸层级:头像不超过 36 磅时使用 10 磅圆点、1 磅边框和 1 磅字形描边;不超过 72 磅时使用 20 磅圆点、2 磅边框和 1.5 磅描边;更大时使用 32 磅圆点、4 磅边框和 2 磅描边。在头像之外时,圆点为 small。 | core AvatarStatusDot 尺寸层级 |
待验证 |
| FR2 | success MUST 以 color.success 填充,且不绘制字形;neutral MUST 以 color.backgroundSurface 填充,并以 color.textSecondary 在内部区域绘制圆环;error MUST 以 color.error 填充,并以 color.onError 在内部区域的四分之三宽度上绘制圆头横条。每个圆点都有 color.backgroundSurface 边框。这些底板是强状态填充色 color.success 和 color.error,其上墨色为匹配的内容角色 color.onSuccess 与 color.onError,与 core 的 token 一致(architecture:theme-tokens INV11)。 |
core AvatarStatusDot 样式 |
待验证 |
| FR3 | 两个初始化器 MUST 构建相同的 AvatarStatusDotProps。基础属性经由 AvatarStatusDotProps 传递:当设置 isHidden 时,视图不绘制任何内容;id 成为辅助功能标识符。 |
Swift component API A2, A3, A7 | 待验证 |
允许的变体¶
- AV1 — 字形绘制。 圆环和条是 SwiftUI 形状,采用 core 的描边宽度,而非 core 的 SVG。
代表性状态¶
| 状态 | 必需不变量 | 允许的变体 |
|---|---|---|
| 每个变体 | 其填充、字形和边框 | AV1 |
| 每个档位 | 其圆点、边框和描边 | 无 |
| 在圆形和方形上 | 由 component:swift/Avatar 放置 |
无 |
| 浅色和深色两种主题 | 每个主题的颜色 | 无 |
转换与优先级顺序¶
- ORD1 — 档位。 头像侧边 → 头像外部的小圆点。
性能与资源¶
- PR1 — 仅形状。 圆点绘制 SwiftUI 形状,并且不加载任何内容。
辅助功能契约¶
- AR1 — 位于头像内。 圆点的标签通过头像的名称传递给 VoiceOver,并且圆点不是单独的元素(Swift 辅助功能 X5)。
- AR2 — 单独存在。 头像外部有标签的圆点是一个以标签命名的图像元素;无标签的圆点会被隐藏(X1)。
- AR3 — 不单独依赖颜色。 每个变体都有其自身形状(X6,Differentiate Without Color)。
- AR4 — 不测量渲染树。 测试断言视图设置的内容;在存在应用托管目标之前,不测量渲染后的辅助功能树。
设计关系¶
| 结构或状态 | 设计要求 | 表征权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 圆点和字形 | Apple Human Interface Guidelines, Accessibility | 由 core 规定 | 辅助 | FR1、FR2 |
该组件实现设计要求,但不复制其设计理由。
平台约束:SwiftUI 没有用于图像的状态徽章控件,因此圆点由 SwiftUI 形状绘制(spec:AST-093 FR2)。指南页面:
Accessibility in the Apple Human Interface Guidelines。
读取的主题值:color.success、color.error、color.onSuccess、color.onError、color.backgroundSurface、color.textSecondary。
族系与系统关系¶
component:AvatarStatusDot拥有变体和档位;本记录仅说明 Swift 如何绘制它们。component:swift/Avatar负责圆点的放置以及组合后的名称。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1 | AvatarStatusDotTests.swift 档位测试 |
36、48、128 点;无头像 | 错误的圆点、边框或描边会导致失败 | audit:swift/AvatarStatusDot/tier |
| FR2 | AvatarStatusDotTests.swift 变体渲染、圆环两侧以及 Y2K 中的忙碌条 |
每个变体处于大档位;neutral、butter、dark;Y2K light,其中 on-error 与 surface 不同 | 错误的填充、缺失的圆环侧边或字形、未采用 on-error 的横条,或 success 上出现字形,都会导致失败 | audit:swift/AvatarStatusDot/look |
| FR3 | AvatarStatusDotTests.swift 初始化器测试;contracts.test.ts |
两个初始化器 | props 不同则失败 | audit:swift/AvatarStatusDot/api |
| AR1, AR2 | AvatarStatusDotTests.swift 组合名称、独立特征和隐藏测试;圆点在渲染树中向其头像报告的标签未被测量(component:swift/Avatar AR3) |
有状态和无状态的名称;带或不带标签的单独圆点 | 组合名称缺少状态标签,或独立圆点缺少其标签和图像特征,则失败 | audit:swift/AvatarStatusDot/a11y |
决策日志¶
未记录任何组件本地决策。
未决问题¶
- OQ1 — 圆点中的自定义图标。(
human-api)Core 的icon是自由格式内容;一旦合约具备共享的图标名称槽位,它就会传递到 Swift。
内容边界¶
本文件不重复消费者的 prop 表/示例、当前审计结果、实施步骤或家族/系统规则。它链接到其所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx