chatkit

语音输入

点语音按钮说话，识别出的文字填进输入框。在 features.voice 里给了 recognize 才显示。

voice.tsx
import { Chatkit, type ChatkitSpeechRecognizer, useChatRuntime } from '@volcengine/chatkit';
import { createMockAdapter } from '@volcengine/chatkit/adapters/mock';
import '@volcengine/chatkit/styles.css';

const adapter = createMockAdapter({});

const SPEECH = '帮我把这个季度的复盘整理成一份文档';

// recognize 由接入方实现：开始收音，把识别结果交给 onText，返回停止函数。
// 这里用一段固定文字代替识别服务：每隔一小段时间多「听」到几个字。
const recognize: ChatkitSpeechRecognizer = ({ onText, onEnd }) => {
  let length = 0;
  const timer = setInterval(() => {
    length = Math.min(SPEECH.length, length + 2);
    const done = length === SPEECH.length;
    onText(SPEECH.slice(0, length), done);
    if (done) {
      clearInterval(timer);
      onEnd();
    }
  }, 150);
  return () => clearInterval(timer);
};

// 语音输入：给了 recognize 才显示。点输入框右下角的语音按钮，文字填进输入框，不会自动发送。
export default function Voice() {
  const runtime = useChatRuntime({ sessionId: 'voice', adapter });
  if (!runtime) return null;
  return (
    <Chatkit runtime={runtime} settings={{ welcome: '点输入框右下角的语音按钮' }} features={{ voice: { recognize } }} />
  );
}
点输入框右下角的语音按钮；示例里识别用一段固定文字代替新窗口打开

用法

recognize 开始收音，把本次识别的累计文本交给回调，返回停止函数（也可以返回解析为停止函数的 Promise）。以下假定语音服务每次返回本次识别的完整文本：

import type { ChatkitSpeechRecognizer } from '@volcengine/chatkit';

const recognize: ChatkitSpeechRecognizer = ({ locale, onText, onEnd, onError }) => {
  const session = mySpeechService.start({ language: locale });
  session.on('partial', text => onText(text, false));
  session.on('final', text => onText(text, true));
  session.on('end', onEnd);
  session.on('error', onError);
  return () => session.stop();
};

<Chatkit sessions={sessions} features={{ voice: { recognize } }} />;

配置项

配置项类型默认说明
features.voice.recognizeChatkitSpeechRecognizer—语音识别实现。
features.voice.slotfalse | ChatkitToolbarSlotName'composer.toolbarEnd'语音按钮的位置；`false` 表示不自动放，由接入方自己摆。

在聊天区外使用与主题继承

VoiceInput 可以放在 Chatkit 插槽中；在页面其他位置使用并将文字写入聊天输入框时，需要放在同一 ChatkitProvider 下，并保留已挂载的 Chatkit 输入框。组件即使能独立显示或启动识别，也不意味着已连接到可写入的输入框。

外置时 VoiceInput 自建主题 wrapper，读取 Provider 的 theme.appearance；使用 inherit 或没有显式模式时读取最近 DOM 主题祖先。Provider 的 root 不会复制到这个 wrapper，自定义颜色需命中它自己的作用域，见调整内置功能。

其普通焦点阴影来自基础 Button 的 --chatkit-shadow-focus。系统强制颜色模式下阴影会被移除，该按钮没有专用的系统色 outline；需要高对比度支持时，宿主应补充可见焦点轮廓，见键盘焦点与强制颜色模式。语音服务和麦克风权限由接入实现负责，需结合目标设备检查，不能通过主题配置开启。

recognize 收到的参数

参数说明
locale当前界面语言
onText传入本次识别的累计文本；第二个参数表示定稿，但当前界面不会据此自动拼接分句或结束识别
onEnd识别结束时调用
onError识别出错时调用

说明

  • 识别服务由业务方选择，chatkit 不连任何语音服务。
  • 语音按钮默认在工具栏右侧；换位置见调整内置功能。
  • 识别出的文字只填进输入框，不会自动发送。
  • 每次 onText 都以“开始识别前的纯文本 + 本次累计识别文本”更新输入框；分句或增量服务需先自行累积。该过程会把已有引用标签转成纯文本，识别期间手动编辑的内容也可能被下一次结果覆盖。
  • 再次点击按钮会调用停止函数；自然结束应调用 onEnd，失败应调用 onError。停止后晚到的识别回调会被忽略。
  • 手动摆放导出的 <VoiceInput /> 时，可以通过它的 recognize 属性提供实现；没有属性或功能配置时会尝试浏览器自带识别。这个回退不会自动开启工具栏的语音功能。