跳转至

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