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-authoringINV7 要求每个语义角色或可主题化部分渲染一个元素。 -
这些条设置了没有隔离的 z-index。 条容器带有
z-index: 1,而包装器并未隔离它,因此这些条会参与页面的层叠顺序。spec:AST-027FR1 将 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