跳转至

ChatDictationButton 组件契约

契约一览

领域 契约
公共契约 ChatDictationButton 带有一个必需的 dictation 状态(isSupported、isListening、volume、bands、toggle)、size(sm、md;默认 md)、isHiddenWhenUnsupported(默认 true)、label、ref、xstyle、className、style 以及 span 属性。
行为 一个仅图标的麦克风 Button,用于切换听写。在聆听时,它显示五个音量响应条而不是麦克风;不支持的听写不渲染任何内容,或者在保持可见时渲染一个禁用 Button。
最终用户影响 语音输入是一个带标签的按钮,说明它是开始还是停止听写;没有语音识别功能的浏览器不会看到无法运行的操作。
构建者影响 无。
兼容性/就绪状态 记录已发布行为;无公开变更。有两个实现缺口,列于当前状态影响之下。
评审检查 拒绝启用的不支持操作、缺失或过时的开始/停止名称、暴露给辅助技术的条,或主题无法重新着色的裁剪颜色。
约束规则 architecture:public-component-api;architecture:theme-tokens INV3;architecture:component-style-authoring INV7;design:reduced-motion。

此表是评审概览;以下正文为权威内容。

意图

ChatDictationButton 是语音识别状态所有者的可见控件。它将该所有者的支持和聆听状态转换为一个仅图标 Button 和五条音量显示。消费者用法见 ChatDictationButton.doc.mjs。

兼容性与迁移

  • 已发布默认值保留:yes
  • 兼容性类别:记录已发布行为;无公开变更
  • 受控/非受控行为:聆听状态由所提供的 dictation 值所有
  • 迁移决策:无

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

当前状态影响

  • 音量条是额外元素。 聆听显示是一个容器和五个条 span 元素,没有任何主题目标会绘制它们。architecture:component-style-authoring INV7 要求每个语义角色或可主题化部分渲染一个元素。

  • 这些条设置了没有隔离的 z-index。 条容器带有 z-index: 1,而包装器并未隔离它,因此这些条会参与页面的层叠顺序。spec:AST-027 FR1 将 z-index 保持为局部,并将此情况列为包含性缺口。

所有权边界

拥有

  • 开始和停止名称,以及调用方的 label 覆盖(FR1、FR2)。
  • 当语音识别不受支持时隐藏或禁用控件(FR3)。
  • 传入 bands 的五条显示及其裁剪颜色(FR2、FR4)。
  • 包装器 span 的 ref、属性和样式(FR5)。

不拥有 / 非目标

  • 语音识别支持检测、生命周期、转录、错误和麦克风权限——由 dictation 状态所有者拥有。
  • 激活、焦点、禁用语义和仅图标呈现——由 component:Button 拥有。
  • 在 ChatComposer 中的放置——调用方的组合。
  • 公开的颜色、阈值或条形状选项。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 所有者 稳定性 无效值行为
Support 受支持;不支持且隐藏;不支持且显示 控件是否渲染以及是否能操作。 每个控件。 不支持时隐藏 component:ChatDictationButton 稳定 TypeScript 拒绝其他值。
Listening 空闲;聆听中 选择开始或停止名称以及麦克风或条。 受支持的控件。 空闲 dictation 所有者 稳定 不适用。
Size sm、md 同时调整 Button 和条的大小。 每个控件。 md component:ChatDictationButton 稳定 TypeScript 拒绝其他值。

行为与布局契约

ID 不变式 依据
FR1 当受支持且空闲时,控件是一个启用的、仅图标的 ghost Button,带有麦克风图标,其名称由 label 或被翻译的启动标签决定,激活时调用 dictation.toggle。 当前源码和测试
FR2 在聆听期间,Button 的名称由 label 或被翻译的停止标签决定,不显示图标,并且五个对辅助技术隐藏的条形会随提供的 bands 缩放。 当前源码和测试
FR3 当听写不受支持时,控件不渲染任何内容;若 isHiddenWhenUnsupported={false},则渲染一个禁用的 Button。 当前源码和测试
FR4 条形使用 --color-accent,当 volume 超过削波阈值时逐渐过渡到 --color-error,从而主题可重新着色两端(architecture:theme-tokens INV3)。 当前源码和测试
FR5 ref、DOM、data 和 ARIA props、className、style 和 xstyle 都会传递到包装 span,该 span 带有 chat-dictation-button 目标;size 同时调整 Button 和条形的大小。 当前源码和测试
FR6 在减少动态效果下,条形会立即改变缩放和颜色,无过渡。 design:reduced-motion;当前源码

允许的变化

  • AV1 — 标签。 调用方可以替换翻译后的启动和停止名称。
  • AV2 — 条形。 条形高度和削波强度随提供的 bands 和 volume 变化。
  • AV3 — 主题颜色。 主题可以更改强调色和错误色。

代表性状态

状态 必需不变式 允许的变化
受支持,空闲 带启动名称的启用的麦克风 Button。 标签、大小。
聆听中 停止名称;五个隐藏的条形。 条形高度。
削波中 条形从强调色向错误色过渡。 主题颜色。
不受支持,默认 不渲染任何内容。 —
不受支持,保持可见 一个禁用的 Button。 标签。

变换与优先级顺序

  • ORD1 — 名称。 优先使用调用方的 label,然后是聆听状态对应的翻译后的启动或停止标签。
  • ORD2 — 支持性。 在应用任何其他状态之前,不受支持且隐藏时先渲染为空。

性能与资源

  • 没有资源规则。

无障碍契约

  • AR1 — 名称。 控件始终具有一个说明其启动或停止听写的名称,除非调用方覆盖了它(FR1、FR2)。
  • AR2 — 装饰性条形。 条形对辅助技术隐藏(FR2)。
  • AR3 — 不可用的操作。 可见的不受支持控件会被禁用(FR3);禁用状态的传达方式由 Button 负责。

设计关系

结构或状态 设计要求 呈现权威 层级角色 组件契约
Button 仅图标的麦克风操作。 component:Button 主要 FR1, FR3
音量条形 显示实时输入电平和削波的五个条形。 当前源 辅助 FR2, FR4, FR6

尚未记录 anatomy-theming 映射;该块在迁移期间是可选的,因此映射被推迟。

家族与系统关系

  • component:Button 负责激活、焦点、禁用语义和仅图标呈现。
  • architecture:theme-tokens 负责条形使用的强调色和错误色角色。
  • design:reduced-motion 负责 FR6 所遵循的减少动态效果规则。
  • 字形和居中的条形是方向中性的;RTL 审计将其记录为不适用。

验证映射

契约 验证 代表性状态 变异或失败预期 审计部分
FR1, AR1 ChatDictationButton.test.tsx "labels and toggles the idle button" 空闲 缺少名称,或激活后未切换,则失败。 audit:ChatDictationButton/behavior
FR2, AR2 ChatDictationButton.test.tsx "shows five hidden visualizer bars and the stop label while listening" 聆听中 条形数量错误、条形暴露,或聆听期间显示启动名称,则失败。 audit:ChatDictationButton/behavior
FR3, AR3 ChatDictationButton.test.tsx 不受支持的测试 不受支持,隐藏和显示 一个被渲染或被启用的不受支持控件则失败。 audit:ChatDictationButton/accessibility
FR4 ChatDictationButton.test.tsx “使用主题自有的颜色作为削波反馈” 削波 用原始颜色替代主题角色时测试失败。 audit:ChatDictationButton/theming
FR5 ChatDictationButton.test.tsx “转发根 ref 和接受的 span 属性” Ref 与 span 属性 遗漏 ref 或属性时测试失败。 audit:ChatDictationButton/api
RTL N/A apps/storybook/rtl-audit/verified-not-applicable.json — — audit:ChatDictationButton/rtl

以下内容从源码读取,尚无聚焦测试:

  • FR1:ghost 变体和麦克风图标。
  • FR2:监听时无图标,条形图随 bands 缩放,并显示调用方的 label。
  • FR4:削波阈值以下的纯强调色。
  • FR5:ARIA 属性到达包装器,className、style 和 xstyle 组合在包装器上,chat-dictation-button 目标以及 sm 尺寸。
  • FR6:移除 reduced-motion 过渡。

决策日志

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

未决问题

无。

内容边界

本文件不重复使用方属性表、语音识别行为或 Button 的规则,而是链接到其归属方。

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