跳转至

ChatLayoutScrollButton 组件契约

契约概览

领域 契约
公共契约 ChatLayoutScrollButton,必填 isVisible 和 onClick,可选 label,以及根 div 透传、样式和 ref。
行为 一个持有单个 ghost Button 的胶囊。隐藏状态不绘制任何内容,并退出 Tab 顺序;非空 label 会展开胶囊并成为可见文本;省略或为空字符串则仅渲染图标。
对最终用户的影响 向上滚动过的读者会获得一个返回最新消息的控件;当他们已在最新消息处时,该控件隐藏且不在 Tab 顺序中。对目标进行重新样式化的主题也会重新绘制他们所看到的胶囊。
对构建者的影响 无。
兼容性/就绪状态 记录已发布行为;无公共变更。三个实现缺口(FR1a、FR3a、FR6a)列在“当前状态影响”下;八个所有者问题仍然开放。
审查检查 拒绝以下情况:目标位于居中行;隐藏胶囊仍保留键盘焦点;非空 label 未同时作为无障碍名称;或某种状态与相反状态绘制结果相同。FR1a、FR3a 和 FR6a 是已记录的缺口,而非验收通过项。
治理规则 architecture:component-theming-surface/INV4;architecture:component-style-authoring/INV1, INV5;architecture:public-component-api/INV5, INV6, INV8;WCAG 2.2 SC 2.4.7 和 SC 2.5.8(AA)。

此表是审查视图;下文正文具有权威性。

意图

ChatLayoutScrollButton 是聊天记录中漂浮的“返回最新消息”操作入口。它拥有胶囊的外观及其可见/隐藏表现;它不拥有任何滚动状态。ChatLayout 默认通过 useChatStreamScroll 和 useChatNewMessages 组合它,调用方可以通过 ChatLayout 的 scrollButton 插槽替换或移除它。

兼容性与迁移

  • 已发布的默认行为保留:yes
  • 兼容性类别:记录已发布行为;无公共变更
  • 受控/非受控行为:可见性是调用方必填输入,组件不持有任何状态
  • 迁移决策:无;DEC-1 记录了目标所在位置

消费者迁移说明应放在消费者文档和发布说明中。

当前状态影响

  • 空 label 会使控件没有名称(FR1a)。 label='' 渲染一个仅含图标的控件,其无障碍名称为空;WCAG 2.2 SC 4.1.2 要求必须有名称(OQ7)。
  • 焦点环被裁剪掉(FR3a)。 胶囊的 overflow: hidden 会裁剪 Button 的外凸焦点环,因此聚焦控件与静止控件看起来一样;WCAG 2.2 SC 2.4.7 要求有可见指示器(OQ8)。
  • 主题无法针对胶囊的状态进行样式化(FR6a)。 胶囊的可见和展开状态会改变其绘制,但目标没有暴露这两种状态,因此主题只能将胶囊作为一个整体重新样式化(OQ1)。

所有权边界

拥有

  • 胶囊表面:其填充、阴影层级、圆角、解析后的高度,以及折叠/展开时的宽度上限。
  • 可见/隐藏表现,包括隐藏时从顺序焦点导航中移除。
  • 调用方未提供 label 时的默认无障碍名称。
  • 在父容器内居中,以及胶囊与其下方内容之间的间距。

不拥有 / 非目标

  • 滚动位置、锁定状态和新消息检测——由 useChatStreamScroll 和 useChatNewMessages 拥有。
  • 在聊天停靠区中的位置,以及该操作入口是否渲染——由 component:ChatLayout 通过其 scrollButton 插槽拥有。
  • 动作语义、焦点环、按压反馈、尺寸几何和变体表面——由 component:Button 拥有,本组件组合了它。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 所有者 稳定性 无效值行为
isVisible true, false 该操作入口是否呈现且可操作 始终 必填 component:ChatLayoutScrollButton 稳定 必填布尔值;无回退
label — 省略 undefined 仅图标;翻译后的默认文本成为无障碍名称 始终 这是默认值 component:ChatLayoutScrollButton 稳定 —
label — 非空 任意非空字符串 可见文本,同时也是无障碍名称 始终 — component:ChatLayoutScrollButton 稳定 —
label — 空 '' 仅图标,且可访问名称为空 — 见 FR1a 始终 — component:ChatLayoutScrollButton 稳定 不应用任何回退;控件没有名称
onClick () => void 激活回调;其类型声明不接收任何参数 始终 必需 component:ChatLayoutScrollButton 稳定 必需;无默认动作
根 div BaseProps<HTMLDivElement> ref、xstyle、className、style 以及其余 DOM 透传属性 始终 无 architecture:public-component-api 稳定 onClick 被排除在继承的 DOM 属性之外

消费者语法与 prop 默认值仍定义于 ChatLayoutScrollButton.doc.mjs。

行为与布局契约

ID 不变式 依据
FR1 控件在每个可达状态下 MUST 暴露非空的可访问名称。 WCAG 2.2 SC 4.1.2
FR1a 省略 label 时使用翻译后的默认值;非空 label 即为名称。实现缺口:label='' 两者都不满足(当前状态影响)。 当前源码
FR2 当 isVisible 为 false 时,该 pill MUST NOT 绘制任何内容,且 MUST NOT 接受焦点(无论是编程式还是顺序式)。 当前源码与测试;WCAG 2.2 SC 2.4.7
FR3 当 isVisible 为 true 时,该 pill MUST 保持键盘可达,并在 Enter 键上激活。 当前源码与测试;WCAG 2.2 SC 2.1.1
FR3a 获得焦点的控件 MUST 绘制可见的焦点指示。实现缺口:焦点环被完全裁剪掉(当前状态影响)。 WCAG 2.2 SC 2.4.7;spec:AST-020/FR1
FR4 非空 label MUST 呈现为可见文本;省略或为空时仅渲染图标,且无可见文本。 当前源码与测试
FR5 该 pill MUST 从 element-size token 获取其解析后的高度,这样任何主题缩放都不会让它裁剪其包裹的 Button。 当前源码与测试
FR6 公共主题化目标 MUST 位于 pill 上——即绘制填充、高度和圆角的元素——而不是位于使其居中的行上。 architecture:component-theming-surface/INV4
FR6a 该目标既不能反映驱动其绘制的可见状态,也不能反映展开状态。实现缺口:主题无法针对任一状态进行设置;目标是否应反映这些状态是 OQ1(当前状态影响)。 当前源码
FR7 状态之间的过渡在 prefers-reduced-motion: reduce 下 MUST 缩短为 0s。 当前源码
FR8 折叠状态下的控件 MUST 至少为 24×24 CSS 像素。 WCAG 2.2 SC 2.5.8 (AA)
FR9 消费者的 ref、样式以及其余 DOM 属性 MUST 到达组件的外层元素。 当前源码与测试;architecture:public-component-api/INV5, INV6, INV8

FR1a — 空 label 的命名缺口。 公共类型允许 label='',而这正是普通调用方代码在字符串为空或尚未加载时产生的值。它以 label=''、aria-label='' 和 isIconOnly={true} 的形式到达 Button,因为 ?? 会直接透传空字符串。Button 仅在 label !== '' 时设置自己的 aria-label,因此调用方的空 aria-label 得以保留;icon-only 不渲染任何可见文本;且 chevron Icon 不携带 label,因此它是 aria-hidden="true"。结果是:一个可聚焦、可操作,但没有可访问名称的控件。

本记录陈述了义务,并记录了当前行为违反该义务的情况。弥合这一差距意味着在回退到默认名称、拒绝该值或将空标签视为调用方错误之间做出选择——这是一个属于所有者的公共API和兼容性决策。参见OQ7。

FR3a — 被裁剪的焦点环。 组合后的Button将其焦点环绘制为边框盒外具有正outline-offset的outline。按钮填满胶囊形容器,而胶囊使用overflow: hidden进行裁剪,以将折叠/展开动画保持在其圆角形状内,因此焦点环的任何部分都不会被绘制。

键盘访问本身是完整的——控件能够获得焦点并激活——因此这是一个可见性缺陷,而非可达性缺陷。补救措施是对胶囊的裁剪方式或焦点环的绘制位置进行生产更改,而这些更改之间的选择会影响渲染的几何形状,因此需要进行视觉审查。记录为OQ8。

FR6a — 未被反映的状态轴。 isVisible在绘制目标上选择可见/隐藏样式,label选择折叠/展开样式,而themeProps('chat-layout-scroll-button')在调用时未传入状态参数。因此,主题可以重新设置胶囊的样式,但无法针对任一状态进行设置。为这些轴命名是新的公开主题化接口,因此其形态属于所有者。参见OQ1。

允许的变化

  • AV1 — 展开宽度。 带标签胶囊的宽度上限是组件设计决策,而非主题值。标签超过该上限后的行为在此处未作定论;参见OQ3。
  • AV2 — 解析后的几何形状。 高度、半径、间距和持续时间从主题令牌解析,因此绝对值会因主题而异,但不会成为回归问题。
  • AV3 — 组合方式。 ChatLayout默认渲染此组件,但调用方可以替换任何节点或完全移除该操作提示。

代表性状态

状态 必需不变量 允许的变化
隐藏 不绘制任何内容,拒绝焦点,保留其布局框(FR2) 过渡持续时间
可见,未提供label 以默认名称命名,可聚焦,至少24×24 CSS像素,无可见文本(FR1、FR3、FR4、FR8) 解析后的胶囊尺寸
可见,非空label 标签既是可见文本也是无障碍名称(FR1、FR4) 展开宽度直至上限
可见,空label 违反FR1 — 仅图标且无障碍名称为空(FR1a) 无;这是一个已记录的缺陷
可见,悬停 指针绘制出与静止状态不同的状态 主题解析出的叠加层
可见,键盘聚焦 违反FR3a — 焦点被持有且:focus-visible匹配,但焦点环被裁剪掉且未绘制任何内容 无;这是一个已记录的缺陷
可见,按下 按下绘制出与悬停和静止状态不同的状态 按下态的处理方式
任何可见状态,已应用主题 文档化的目标重新绘制胶囊(FR6);其状态轴不可达(FR6a) 主题声明的属性

性能与资源

  • PR1 — 无状态、无副作用、无观察者。 该组件在渲染期间仅从其props推导所有渲染差异,并且不注册任何监听器、定时器、观察者或动画帧。

无障碍契约

  • AR1 — 具名。 控件MUST在每个可达状态下暴露非空的无障碍名称(WCAG 2.2 SC 4.1.2)(FR1)。省略label和非空label满足此要求;label=''不满足,该差距记录为FR1a而非在此处解决。
  • AR2 — 焦点跟随绘制。 不绘制任何内容的控件MUST NOT可聚焦,因为焦点落在其上时将没有可见指示器(WCAG 2.2 SC 2.4.7)。opacity和pointer-events无法实现这一点;visibility可以(FR2)。
  • AR3a — 焦点可见。 聚焦的控件MUST绘制焦点指示器(WCAG 2.2 SC 2.4.7)。焦点环已声明但被裁剪掉;记录为FR3a而非在此处解决。
  • AR3 — 目标尺寸。 折叠状态的控件MUST至少为24×24 CSS像素(WCAG 2.2 SC 2.5.8 AA)(FR8)。
  • AR4 — 减少动态效果。 状态转换在prefers-reduced-motion: reduce下MUST折叠为0s(FR7)。
  • AR5 — 翻译字符串。 默认无障碍名称MUST通过翻译器目录解析,绝不可使用字面量。

设计关系

解剖结构或状态 设计需求 表征权威 层级角色 组件契约
胶囊表面 悬浮于转录内容上方的操作提示 未定(unsettled) 支撑性 FR5、FR6
隐藏状态 缺席而非变暗 未定(unsettled) 支撑性 FR2、AR2
带标签状态 文本与字形同处一个胶囊 未定(unsettled) 支撑性 FR4

组件实现设计需求,但不复制其背后的原理。unsettled(未定)的表征仍然是人工决策;原则不允许代理自行发明答案。目前没有authority: current设计记录涵盖悬浮滚动操作提示,因此这些行记录的是差距而非需求。

家族与系统关系

  • family:buttons拥有此组件通过component:Button组合而成的操作表面。此组件不是其成员:其公开目的是包含按钮的转录内容操作提示,而该家族的成员规则排除那些仅将Button用作操作槽的组件。参见OQ4。
  • architecture:component-theming-surface拥有此组件主题化必须满足的目标/解剖结构关系;FR6直接采用INV4。
  • spec:AST-029拥有本记录验证映射所遵循的审计证据清单。

验证映射

契约 验证 代表性状态 变更或失败预期 审计章节
FR1, FR4 ChatLayoutScrollButton.test.tsx role/name 和可见文本用例 省略 label;非空 label 移除 isIconOnly 会将翻译后的名称渲染为被裁剪的可见文本,且名称用例仍然通过 audit:ChatLayoutScrollButton/a11y
FR1a 无专项测试;通过三个文件从源码读取(?? 将 '' 透传,Button 的 label !== '' 防护,Icon 的装饰性默认值)。 label 为空 若在此处添加回退,会让推导结果在没有测试失败的情况下变得过时 audit:ChatLayoutScrollButton/a11y
FR2, FR3 ChatLayoutScrollButton.test.tsx 的 Tab 用例;ChatLayoutScrollButton.a11y.chromium.spec.ts 静止时隐藏;向上滚动后显示;再次隐藏 单独用 opacity 替代 visibility 会使不可见控件保留在 Tab 顺序中 audit:ChatLayoutScrollButton/a11y
FR3a ChatLayoutScrollButtonSurface.a11y.chromium.spec.ts 交互测试环节:将聚焦帧的字节与同一页面捕获的静止帧进行比较;并以裁剪祖先的余量为参照测量焦点环的外向延伸(记录为 ringChangedPixels、outreach、roomPx) 已折叠并带 label;浅色和深色 结果仅被记录和注释、从不进行断言,因此修复裁剪无法让该检查变红 audit:ChatLayoutScrollButton/a11y
FR5 ChatLayoutScrollButton.a11y.chromium.spec.ts 双主题几何对 neutral 和 butter 字面高度会让更大的元素缩放时裁剪掉胶囊所包裹的 Button audit:ChatLayoutScrollButton/theming
FR6 ChatLayoutScrollButtonSurface.a11y.chromium.spec.ts 的放置与探针主题可达性测试 可见、折叠、neutral 和 probe 将目标移回居中行会让胶囊在 probe 主题下保持不变 audit:ChatLayoutScrollButton/theming
FR6a 源码:themeProps() 调用时未传 state 参数,且 Chat.doc.mjs 声明目标时没有 visualProps/states 可见/隐藏;折叠/展开 添加任一轴都是新的公共主题表面,因此在所有者决定之前,任何测试都不得断言其形状 audit:ChatLayoutScrollButton/theming
hover, pressed ChatLayoutScrollButtonSurface.a11y.chromium.spec.ts 交互测试环节——每个帧都断言匹配了伪类,且捕获的字节与同一页面的静止帧不同 已折叠并带 label;浅色和深色 在释放后或指针位于别处时捕获的帧,将无法通过其自身的交互断言 audit:ChatLayoutScrollButton/design
FR8 ChatLayoutScrollButtonSurface.a11y.chromium.spec.ts 测量的目标框 可见、折叠 解析后的尺寸更小会让控件低于 AA 最低要求 audit:ChatLayoutScrollButton/a11y
FR9 ChatLayoutScrollButton.test.tsx 透传用例 任意 移除 ...rest 会静默丢弃调用方设置的 data-*、id 和 ARIA audit:ChatLayoutScrollButton/public-api

从源码读取,尚无聚焦测试:

  • FR1a:label='' 产生一个空的无障碍名称。
  • FR6a:目标不反映任何状态。
  • FR7:在减少动态效果(reduced motion)下,过渡时间缩减为 0s。

决策日志

DEC-1 — 公共主题目标位于胶囊之上,而非位于将其居中的行上

参考: component:ChatLayoutScrollButton/DEC-1 决策者: cixzhang,2026-09-23

该组件渲染两个元素:一个用于居中胶囊并保持其下方间距的全宽行,以及负责绘制填充、高度和圆角的胶囊。公共目标位于胶囊上,即主题重新设置样式的元素,符合 architecture:component-theming-surface/INV4 的要求。消费者的 ref、样式和 DOM props 保留在外层行上(FR9)。

已拒绝:为胶囊增加第二个目标 —— 为一个已绘制的部件新增主题表面。

已拒绝:将消费者的透传移至胶囊 —— 这会改变调用方 id 和 ref 的解析位置。

未决问题

  • OQ1 —— 目标是否应反映其驱动样式的状态?(human-api) 胶囊在可见/隐藏与折叠/展开的样式对象之间进行选择,而 themeProps 两者都不反映,因此主题无法分别处理任一状态。暴露它们意味着在公共目标上添加 visualProps/states,这是新的主题表面,而非修复。

  • OQ2 —— 在非 layer 组件上,isVisible 是否是合适的名称?(human-api) 共享约定将 isOpen/isVisible 保留给 layer 组件。该 prop 已在 @astryxdesign/core@0.6.3 中发布,因此任何更改都是破坏性的,需要做出兼容性决策。

  • OQ3 —— 超出展开上限的 label 应如何处理?(human-design) 胶囊在其宽度上限处裁剪,没有省略号也不换行。无障碍名称仍然保留,因此只有有视力的读者会丢失文本,而区域设置扩展是现实中的触发因素。没有 authority: current 的设计记录涵盖此表面的截断规则。

  • OQ4 —— 该组件是否属于 family:buttons?(human-api) 其公共用途是聊天记录的一种操作控件,并且它不在该家族的成员列表中,但它是一个仅由 Button 组合而成、没有其他内容的组件。上述解读采用了家族契约中关于“仅将 Button 用作触发器或操作插槽的组件”的排除条款。

  • OQ5 —— 对胶囊的 max-width 进行动画处理是否可接受?(human-design) 展开和折叠会对布局属性进行动画处理。已遵守减少动态效果(reduced motion)的偏好,且子树是一个按钮,但本应管辖动画属性的记录 design:motion 目前是 authority: draft。

  • OQ6 —— 消费者文档没有结构清单。(human-api) architecture:component-theming-surface 将此记录为 Core 中尚未完成的迁移工作,因此这里不写 ### Theming anatomy 块:没有已发布的结构名称可供其映射。

  • OQ8 —— 焦点环应如何逃出胶囊的裁剪区域?(human-design) 胶囊需要 overflow: hidden 来实现其折叠/展开动画,而 Button 的焦点环绘制在其边框盒之外,因此两者直接冲突。候选方案——将按钮内缩以容纳焦点环、在胶囊上绘制焦点环、或在另一个元素上进行裁剪——都会改变渲染几何,且属于视觉评审范畴。

  • OQ7 —— label='' 应该做什么?(human-api) 它会产生一个无名称的控件(FR1a)。候选答案——回退到已翻译的默认值、在类型中拒绝该值、或将其视为调用方错误——是针对已发布 prop 的公共 API 和兼容性决策,因此本记录只陈述这一缺口,而不做选择。

内容边界

本文件不重复消费者 prop 表格/示例、当前审计结果、实施步骤或家族/系统规则。它会链接到相应的归属方。

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