# 语音输入按钮

## 使用方法

`ChatDictationButton` 是对话输入区里那种「按一下开始说、再按一下停」的按钮。它跟 `useChatDictation` 配对使用：没在听的时候显示话筒图标，正在听的时候显示跳动的音量条。放在 `ChatComposer` 的 `sendActions` 插槽里。

```ts
import { ChatDictationButton } from '@astryx-vue/core/Chat'
```

### 结构

- **话筒图标**: 空闲状态下显示。点它就开始语音输入。
- **音量条**: 正在听的时候顶替图标的跳动竖条，跟着真实麦克风音量动。
- **幽灵按钮**: 底下的 Button，variant 为 ghost、isIconOnly，负责点击区域和聚焦环。

## 建议

| 指引 | 实践 |
| --- | --- |
| 推荐 | 把语音按钮放进 `ChatComposer` 的 `sendActions` 插槽，它就挨着发送按钮，正是用户找语音入口的位置。 |
| 推荐 | 把输入框的句柄传给 `useChatDictation`，用户说话时半截的话会以灰字出现在输入框里。 |
| 推荐 | 给 `useChatDictation` 打开 `hasSounds`，开始和结束录音时给一声提示音。按钮变化本来就很细微，有声音更好判断。 |
| 避免 | 把语音按钮拿到对话输入区外面单独用。它是为输入区发送按钮旁边那个位置设计的，不是通用的录音控件。 |
| 避免 | 忘了处理浏览器不支持的情况。浏览器没有 SpeechRecognition 时按钮会自己藏起来，但你的输入区本身也得在不支持时能用。 |

## 示例

常见的用法、变化和状态。

### ChatDictationButton — 基础

接上 useChatDictation、放在 ChatComposer 的 sendActions 插槽里的语音按钮。点话筒，说的话就转成文字进输入框。

```vue
<script setup lang="ts">
import type { ChatComposerInputHandle } from '@astryx-vue/core/Chat'
import { ChatComposer, ChatComposerInput, ChatDictationButton, useChatDictation } from '@astryx-vue/core/Chat'
import { reactive, ref } from 'vue'

const input = ref<ChatComposerInputHandle | null>(null)
const dictation = reactive(useChatDictation({ input }))
</script>

<template>
  <ChatComposer>
    <template #input>
      <ChatComposerInput ref="input" />
    </template>
    <template #sendActions>
      <ChatDictationButton :dictation="dictation" />
    </template>
  </ChatComposer>
</template>
```

## 属性

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `dictation` | `{ isSupported, isListening, bands, volume, toggle }` | — | 必填。`useChatDictation` 或 `useSpeechRecognition` 的返回值。用 `reactive()` 包一层也认，每个字段都会跟着变。 |
| `size` | `'sm' \| 'md'` | `'md'` | 按钮尺寸，交给 `Button`，同时决定那些竖条的宽和高。 |
| `isHiddenWhenUnsupported` | `boolean` | `true` | 浏览器没有语音识别能力时把这个控件藏起来。设成 `false` 就留在原地，只是禁用。 |
| `label` | `string` | 本地化的“Start dictation” / “Stop dictation” | 按钮给读屏用的名字。 |

正在听的时候按钮用强调色。输入音量超过爆音线时，竖条会往错误色偏，麦克风太响一眼就能看出来。