跳转至

Avatar (Swift) 组件合约

合约概览

领域 合约
公共合约 Avatar(_ name: String? = nil, src:, fallbackSrc:, alt:, size: AvatarSize?, shape: AvatarShape?, tooltip: AvatarTooltip?, href:, status:, onClick:) 以及 Avatar(_ props: AvatarProps, status:),是模块 Astryx 中的一个 SwiftUI View。size 是 xsm 到 xl 的命名尺寸。
行为 按顺序绘制 src 处的图像,否则使用 fallbackSrc,否则在主题的中性色底板上根据 name 生成姓名首字母,否则显示人物符号,并按形状裁剪。当提供 href 时,它是 SwiftUI Link;仅有 onClick 时,它是按钮;无论哪种方式,绘制效果相同。
最终用户影响 用户会看到与 Web 上相同的图片、姓名首字母和形状;VoiceOver 会朗读该头像的名称,或跳过装饰性头像。
构建者影响 应用传入名称和图片 URL,并可选择传入提示文字和 AvatarStatusDot。像素尺寸、target 和 rel 没有对应的 Swift 形式;href 必须是绝对 URL。
兼容性/就绪状态 增量式:新增一个视图和生成的 AvatarProps。草稿;已在 macOS 和 iOS 模拟器上构建并测试;设备截图附于该变更。
审查检查 拒绝超出合约的尺寸或形状、禁用状态、绘制效果与静态头像不同的链接或按钮、为触控目标而扩展的布局,或没有名称却被 VoiceOver 朗读的静态头像。
管理规则 spec:AST-082 FR3、FR4、FR7;spec:AST-093 FR1–FR5;packages/native/specs/swift/library/ 下的 Swift 组件 API(A1–A9)、主题环境和辅助功能记录。

此表是审查投影;以下正文为权威内容。

意图

Apple 平台上的 Avatar 以 core 的兜底顺序、尺寸、形状和命名规则展示个人或实体的图片,并使用 SwiftUI 自身的图片加载能力以及链接和按钮控件进行绘制。

兼容性与迁移

  • 已发布的默认值保留:not yet released
  • 兼容性类别:增量式
  • 受控/非受控行为:不适用
  • 迁移决策:无

使用者迁移说明属于使用者文档和发布说明。

所有权边界

拥有

  • 使用 SwiftUI AsyncImage 加载 src,然后加载 fallbackSrc。
  • 姓名首字母、人物符号、底板颜色和形状裁剪。
  • 在 href 或 onClick 时切换到 SwiftUI Link 或 Button,而不改变绘制效果。
  • 头像的 VoiceOver 名称及其触控目标。

不拥有 / 非目标

  • props 的含义、姓名首字母规则和尺寸刻度——由 component:Avatar 拥有。
  • Avatar 组,没有对应的 Swift 视图。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态可用性 默认值 拥有者 稳定性 无效值行为
size xsm、sm、md、lg、xl 在默认文本大小下为 20、24、36、48、128 点 始终 md component:Avatar 实验性 core 的像素尺寸没有对应的 Swift 形式
shape circle、rounded、square 全圆、主题的元素圆角、无圆角 始终 circle component:Avatar 实验性 无
picture 图片、兜底图片、姓名首字母、人物符号 按顺序取第一个可用的项 始终 — component:Avatar 实验性 空 URL 或无法加载的 URL 会跳到下一项
control static、link(href)、button(onClick) 点击行为;绘制效果相同 始终 static component:swift/Avatar 实验性 非绝对 URL 的 href 会让头像保持静态,或成为按钮

行为与布局合约

ID 候选不变量 依据 草稿审阅状态
FR1 视图 MUST 在 src 处显示图像;当它不存在或加载失败时,显示 fallbackSrc 处的图像;然后显示来自非空白 name 的首字母;最后显示人形符号。后备图像仅在 src 失败后或没有 src 时才加载;在图像加载期间,显示首字母或人形符号。 核心 Avatar 后备顺序;spec:AST-093 FR2 待验证
FR2 首字母 MUST 遵循核心规则:取第一个和最后一个具有字母、数字或表情符号的单词的首个字母、数字或表情符号并转为大写,跳过前导标点,保留完整的表情符号、旗帜或联合表情符号序列。不含此类字符的名称显示人形符号,并仍以该名称命名头像。 核心 Avatar 首字母 待验证
FR3 在默认文本大小下,头像对于 xsm 到 xl MUST 是 20、24、36、48 或 128 点的正方形,并随 Dynamic Type 最多增大 1.6 倍且绝不缩小,从而使头像及其首字母与旁边的名称一同增大,而不会吞掉一行(spec:AST-082 FR11)。它被裁剪为圆形、主题的 radius.element 或正方形。 核心 Avatar 尺寸与形状 待验证
FR4 首字母和人形符号 MUST 在 color.neutral 上以 color.textSecondary 绘制;首字母使用主题的正文字体族、中等字重,大小为边长的 40%。 核心 Avatar 后备样式;spec:AST-093 FR4 待验证
FR5 当 href 是绝对 URL(带有 scheme)时,头像 MUST 是 SwiftUI Link,但脚本 URL(javascript:、vbscript:)或 data: URL 中的 HTML 文档 MUST 使其不带链接,而是作为带 onClick 的按钮或静态显示(family:navigation-destinations FR4);若同时存在 onClick,则在打开时运行 onClick,随后 URL 交由应用自身的 URL 处理器或系统处理器处理。href 不是绝对 URL(如 web 路径)时,MUST 通过一条指明该路径的消息阻止开发构建;发布构建则绘制不带链接的头像,作为带 onClick 的按钮或静态显示。仅有 onClick 时,使用 SwiftUI Button。两种情况都完全按静态头像绘制,且头像没有禁用状态。 Swift 组件 API A4 待验证
FR6 两个初始化器MUST构建相同的 AvatarProps;name 是第一个无标签参数,单个尾随闭包是状态,onClick 位于最后。基础属性通过 AvatarProps 传递:当 isHidden 为真时视图不绘制任何内容;id 成为辅助功能标识符。 Swift 组件 API A2–A4, A7;spec:AST-082 FR7 verify
FR7 status 槽位MUST像核心放置任何状态那样,在同一布局遍历中,根据内容自身尺寸,在头像裁剪区域之外绘制其内容(通常是一个 AvatarStatusDot):对于圆形头像,状态位于以圆形边缘底部 trailing 45° 点为圆心的圆上;对于圆角或方形头像,状态从底部 trailing 角悬出,悬出量为该状态尺寸的四分之一;在从右到左(RTL)布局中镜像。它MUST NOT改变头像的尺寸或布局;它给圆点提供头像的边长作为其尺寸档位,并让其他内容随 Dynamic Type 的增长不快于头像,直至其 1.6 倍增长时的文本大小:内容仍会随 Dynamic Type 增长(spec:AST-082 FR11),但不超过其属主的增长,因为属主决定其容纳内容的尺寸(Swift slots S4)。 core Avatar status position; Swift slots S4 verify
FR8 tooltipMUST像核心那样解析:对于 nil 或 true 解析为名称,对于字符串解析为给定词语,对于 false 或空白词语解析为无;并且MUST通过 Astryx Tooltip 显示(architecture:native-swift-library-tooltip),其焦点和触摸状态由下方“按输入的 Tooltip”表格规定:静态头像仅在显示 Tooltip 时才是 Tab 停留点,正如核心仅在这种情况才给其根节点 Tab 停留点;点击时打开 Tooltip;链接或按钮保持其焦点和点击行为。聚焦的头像显示平台的焦点环,正如核心显示其 focus-visible 环。给定词语即 VoiceOver 提示。在传输时,它就是 Web 值:一个字符串或一个 Bool。 core Avatar tooltip; core Tooltip; spec:AST-082 FR3 verify

按输入的 Tooltip(FR8)。 Astryx Tooltip 的规则适用;此表说明 Avatar 的选择。

输入 默认名称 给定词语 关闭(false 或空白)
指针 气泡会在 200 ms 后于头像上方显示名称;指针停留在其上时保持显示;按下时隐藏 同上,显示给定词语 无
键盘焦点 气泡立即显示名称,Escape 隐藏它;静态头像是一个 Tab 停留点 同上,显示给定词语 无;静态头像不是 Tab 停留点
触摸轻点 直接轻点静态头像会打开带名称的气泡;再次轻点它,或轻点其他任意位置,则关闭气泡,且该轻点仍会到达其所落于的元素;该轻点与所在行共享;链接或按钮保持其点击行为 同上,显示给定词语 无
VoiceOver 名称作为头像自身被朗读一次;气泡隐藏,点击不触发 这些词语就是提示,与 core 将其放入描述中的方式一致 无

允许的变体

  • AV1 — 加载。 图片加载时,显示首字母或人形符号,而不是空白底板。
  • AV2 — 字形。 人形符号是 SF Symbol person.fill,而非 core 的 SVG。

  • AV3 — 工具提示外观。 工具提示是 Astryx 工具提示的气泡,在所有输入上使用 core 的工具提示颜色。SwiftUI 的 .help 不适用:它同时也是 VoiceOver 提示,因此会把名称朗读两次,而且它按系统的外观和延迟显示,不会在键盘聚焦或点击时出现。

代表性状态

状态 必需不变式 允许的变体
图片 图片填充形状 图片内容
加载失败且有后备图 后备图 无
首字母,各种尺寸和形状 首字母在中性底板上居中 字形度量
无名称 人形符号占边长的 60% 无
链接和按钮 与静态时相同的绘制 无
浅色和深色,两套主题 各主题的底板和文本颜色 无

转换与优先级顺序

  • ORD1 — 图片。 src → fallbackSrc → 首字母 → 人形符号。
  • ORD2 — 名称。 alt → name,空白字符串视为无;然后与状态标签(AR6)组合,圆点标签优先于其他元素的标签。
  • ORD3 — 控件。 href(链接)→ onClick(按钮)→ 静态。

性能与资源

  • PR1 — 系统加载。 图片通过 AsyncImage 和系统 URL 缓存加载;视图自身不保留任何图片缓存。

辅助功能契约

  • AR1 — 具名或装饰性。 具有名称的静态头像是一个由 alt 命名的图像元素,否则由 name 命名,并与状态标签(AR6)组合;如果既无名称也无状态标签,则对 VoiceOver 隐藏。链接或按钮头像是一个具有链接或按钮特征且名称相同的元素;首字母永远不会成为单独的元素(Swift 辅助功能 X1、X5)。
  • AR2 — 触控目标。 链接或按钮头像,以及点击可打开工具提示的静态头像,在至少 44×44 pt 的范围内响应点击,且不改变其绘制尺寸或布局(X7)。
  • AR3 — 不测量渲染树。 测试只断言视图所设置的内容;在有应用托管目标之前,不测量渲染出的辅助功能树和点击区域。
  • AR4 — 未命名的点击会被标记。 没有 alt 或 name 的链接或按钮头像会记录一条开发警告,与 core 的警告方式一致。
  • AR5 — 首字母对比度。 首字母使用 core 的令牌绘制,color.textSecondary 位于 color.neutral 之上,与 core 的 Avatar 一致。在默认主题和中性主题的深色外观下,这对颜色低于 4.5:1,core 中也是如此;修复应属于主题令牌。
  • AR6 — 状态加入名称。 状态标签会像 core 的消息组合方式那样加入头像名称(“Ada Lovelace, Online”);单独的状态标签也可为原本无名的头像命名。该标签来自插槽中的 AvatarStatusDot 或带标签的 Icon,可在任意层级,因为 core 会读取作为 status 传入的元素的 label,且圆点标签优先,与 core 报告的圆点标签行为一致;SwiftUI 无法读取其他视图中的标签,因此它们的标签不会加入。

设计关系

构成或状态 设计要求 呈现权威 层级角色 组件契约
照片、首字母 Apple Human Interface Guidelines, Images 由 core 规定 突出 FR1–FR4

该组件实现设计要求,但不复制其设计理由。

平台控件:图片使用 SwiftUI AsyncImage,href 使用 SwiftUI Link,onClick 使用 SwiftUI Button(spec:AST-093 FR2)。SwiftUI 没有头像控件,因此底板、首字母和裁剪在此处绘制。指南页面:Apple Human Interface Guidelines 中的 Images、Buttons 和 Accessibility。

读取的主题值:color.neutral、color.textSecondary、radius.element、font.family.body、font.weight.medium 和 Bold Text;工具提示气泡使用 color.textPrimary、color.backgroundSurface、space.s1、space.s2、radius.container,以及正文文本大小和字重。

家族与系统关系

  • component:Avatar 拥有 props、尺寸、首字母规则和后备顺序;本记录只说明 Swift 如何绘制它们。
  • 持有插槽中 Avatar 的属主会将未设置尺寸的 Avatar 保留为 md(Swift 插槽 S4)。

验证映射

契约 验证 代表性状态 变异或失败预期 审计章节
------------- --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ------------------------------------------------------------------------------------------------------------------- --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ----------------------------
FR1, FR2 AvatarTests.swift 姓名缩写与回退测试 core 的姓名缩写场景;空白和符号名称 错误的姓名缩写或缺失的人物符号将导致失败 audit:swift/Avatar/picture
FR3, FR4 AvatarTests.swift 大小、文本尺寸增长、形状和双主题渲染 每种大小;xx-large 和最大文本尺寸;圆形和方形;浅色、深色、butter 错误的边长、无增长或增长超过 1.6 倍、有未裁剪的角、或使用自身颜色,均导致失败 audit:swift/Avatar/look
FR5, AR2, AR4 AvatarTests.swift 链接和按钮渲染;点击、特征、点击区域、警告、linkURL、web 路径和拒绝目标测试 静态、链接、按钮;格式错误、相对和空 href;javascript:、vbscript: 和 data:text/html href 链接或按钮绘制不同、格式错误的 href 被当作链接、web 路径未被标记、未标记的无名点击、或拒绝的目标被当作链接,均导致失败 audit:swift/Avatar/control
FR8 AvatarTests.swift 提示文字、焦点和触摸、VoiceOver 提示及 wire 测试;TooltipPresenterTests.swift 覆盖每种输入;contracts.test.ts;parseDocType.test.ts 名称、true、文字、false、空白、无名称;静态、链接、按钮 错误的提示、静态头像不是 Tab 停靠点或点击时不展开、控件无法点击、或 wire 值与 web 不一致,均导致失败;在出现相应测试之前不衡量:静态头像不显示提示但获得焦点,或聚焦头像没有焦点环 audit:swift/Avatar/tooltip
FR6 AvatarTests.swift 初始化器和隐藏测试;contracts.test.ts 两种初始化器;isHidden;命名大小 属性不同、隐藏头像被绘制、或 Swift 中使用像素大小,均导致失败 audit:swift/Avatar/api
FR7, AR6 AvatarStatusDotTests.swift 在测量位置对状态点和其它内容的放置渲染、大小、最大文本尺寸下图标的增长、状态点-标签优先、以及名称测试;将标签带入渲染名称的标签偏好未被衡量(AR3) lg 尺寸下的圆形和方形;有状态和无状态的名称 状态点改变头像大小、超出边缘、或导致名称缺少标签,均导致失败 audit:swift/Avatar/status
AR1 AvatarTests.swift 命名与特征测试 alt、name、空白、无 错误的名称或带有名称的装饰性头像将失败 audit:swift/Avatar/a11y
AR5 AvatarTests.swift 双主题渲染使用 core 的 tokens 绘制首字母 默认与中性,浅色与深色 使用 core 之外的 tokens 的首字母将失败 audit:swift/Avatar/look

决策日志

未记录任何组件本地决策。

开放问题

无。

内容边界

本文件不重复使用方 prop 表格/示例、当前审计结果、实现步骤或家族/系统规则,而是链接到相应的负责人。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx