syncfusion-react-speech-to-text

Syncfusion React SpeechToText 组件

组件概览

SpeechToText 组件可使用 Web Speech API 将语音转换为文本。此技能可帮助你在 React 应用中实现、定制和排查语音识别问题。该核心组件通过浏览器 API 从用户的麦克风捕获音频，并实时将语音转换为文本。

主要功能

• 实时语音识别
• 支持多种语言
• 可定制按钮和工具提示
• 事件驱动架构
• 通过方法进行编程控制
• 支持无障碍功能（ARIA 标签、键盘导航）
• 支持本地化
• 错误处理与恢复

文档

入门

📄 阅读： references/getting-started.md

• 通过 npm 安装
• 包的安装与配置
• 基本组件实现
• CSS 导入和主题选择
• 第一个可运行示例
• TypeScript 配置
• 禁用组件（disabled 属性）

语音识别功能

📄 阅读： references/speech-recognition-features.md

• 实时获取转录文本
• 设置识别语言
• 管理临时结果
• 使用 SpeechToTextState 枚举（Inactive、Listening、Stopped）管理聆听状态
• 从事件参数和组件引用中读取 listeningState
• 处理语音转文本转换
• 实时结果与最终结果

按钮和工具提示定制

📄 阅读： references/button-and-tooltip-customization.md

• 定制按钮内容和图标
• 图标位置和样式
• 控制工具提示的显示状态（showTooltip 属性）
• 工具提示配置和位置（全部 12 个 TooltipPosition 值）
• CSS 类样式（e-primary、e-success 等）
• 按钮外观模式
• 响应式按钮设计

事件和方法

📄 阅读： references/events-and-methods.md

• 事件处理（created、onStart、onStop、onError、transcriptChanged）
• 正确的事件参数接口（StartListeningEventArgs、StopListeningEventArgs、ErrorEventArgs、TranscriptChangedEventArgs）
• 使用 cancel 属性阻止开始聆听
• 使用 isInteracted 区分用户触发与编程触发
• 使用 errorMessage 获取易于理解的错误详情
• 使用 isInterimResult 区分临时与最终转录结果
• startListening()、stopListening() 和 destroy() 方法
• 基于引用的组件控制
• 编程管理聆听状态

全球化和本地化

📄 阅读： references/globalization-and-localization.md

• 使用 L10n.load() 进行本地化
• 可用的区域设置字符串和翻译
• 特定语言的错误消息
• 支持从右向左书写的语言
• 无障碍标签和 ARIA 属性
• 使用 htmlAttributes 为按钮元素设置自定义 HTML/ARIA 属性
• 支持多语言界面

故障排查和安全

📄 阅读： references/troubleshooting-and-security.md

• 常见问题和解决方案
• 浏览器兼容性矩阵
• 麦克风权限处理
• 安全注意事项和最佳实践
• 隐私和数据传输
• 性能优化
• 离线回退策略

快速入门示例

import { SpeechToTextComponent, TextAreaComponent, TranscriptChangedEventArgs } from '@syncfusion/ej2-react-inputs';
import { useState } from 'react';
import "@syncfusion/ej2-tailwind3-theme/styles/speech-to-text/index.css";

function VoiceNoteApp() {
  const [transcript, setTranscript] = useState('');

  const handleTranscriptChanged = (args: TranscriptChangedEventArgs) => {
    setTranscript(args.transcript);
  };

  return (
    <div style={{ padding: '20px' }}>
      <h2>Voice Note Recorder</h2>
      
      {/* SpeechToText component with microphone button */}
      <SpeechToTextComponent 
        id="speechToText"
        transcriptChanged={handleTranscriptChanged}
      />
      
      {/* Display transcribed text */}
      <TextAreaComponent
        id="noteArea"
        value={transcript}
        resizeMode="None"
        rows={5}
        cols={50}
        placeholder="Your voice will appear here..."
      />
    </div>
  );
}

export default VoiceNoteApp;

常见模式

模式 1：语音表单输入

import { SpeechToTextComponent, TextBoxComponent } from '@syncfusion/ej2-react-inputs';
import { useState } from 'react';

function VoiceForm() {
  const [formData, setFormData] = useState({
    name: '',
    message: ''
  });

  const handleNameTranscript = (args: any) => {
    setFormData(prev => ({ ...prev, name: args.transcript }));
  };

  const handleMessageTranscript = (args: any) => {
    setFormData(prev => ({ ...prev, message: args.transcript }));
  };

  return (
    <div>
      <label>Name (speak):</label>
      <SpeechToTextComponent transcriptChanged={handleNameTranscript} />
      <TextBoxComponent value={formData.name} />
      
      <label>Message (speak):</label>
      <SpeechToTextComponent transcriptChanged={handleMessageTranscript} />
      <TextBoxComponent value={formData.message} />
    </div>
  );
}

模式 2：编程控制

import { SpeechToTextComponent } from '@syncfusion/ej2-react-inputs';
import { useRef } from 'react';

function VoiceControlApp() {
  const speechRef = useRef<SpeechToTextComponent>(null);

  const startVoiceInput = () => {
    speechRef.current?.startListening();
  };

  const stopVoiceInput = () => {
    speechRef.current?.stopListening();
  };

  return (
    <div>
      <SpeechToTextComponent ref={speechRef} />
      <button onClick={startVoiceInput}>Start Recording</button>
      <button onClick={stopVoiceInput}>Stop Recording</button>
    </div>
  );
}

模式 3：错误处理

import { SpeechToTextComponent, ErrorEventArgs } from '@syncfusion/ej2-react-inputs';
import { useState } from 'react';

function VoiceWithErrorHandling() {
  const [error, setError] = useState('');
  const [isListening, setIsListening] = useState(false);

  const handleError = (args: ErrorEventArgs) => {
    // args.errorMessage is the human-readable description; args.error is the error code
    setError(args.errorMessage || `Error: ${args.error}`);
  };

  const handleStart = () => {
    setIsListening(true);
    setError('');
  };

  const handleStop = () => {
    setIsListening(false);
  };

  return (
    <div>
      <SpeechToTextComponent 
        onError={handleError}
        onStart={handleStart}
        onStop={handleStop}
      />
      {isListening && <p>🎤 Listening...</p>}
      {error && <p style={{ color: 'red' }}>{error}</p>}
    </div>
  );
}

关键属性

属性	类型	描述
lang	string	语音识别语言（例如，'en-US'、'fr-FR'）
transcript	string	当前转录文本
allowInterimResults	boolean	显示实时结果（默认：true）
listeningState	SpeechToTextState	当前监听状态（Inactive、Listening、Stopped）
buttonSettings	ButtonSettingsModel	自定义按钮外观和内容
tooltipSettings	TooltipSettingsModel	配置工具提示的显示方式
showTooltip	boolean	是否在悬停时显示工具提示（默认：true）
cssClass	string	应用用于样式设置的 CSS 类
disabled	boolean	禁用所有组件交互（默认：false）
htmlAttributes	{ [key: string]: string }	根按钮元素的附加 HTML 属性（ARIA、data-* 等）
locale	string	本地化语言代码
enableRtl	boolean	启用从右到左的布局
enablePersistence	boolean	通过 localStorage 在页面重新加载期间保留组件状态

事件处理程序

事件	参数	描述
created	-	组件初始化时触发
onStart	StartListeningEventArgs	开始语音识别时触发。参数：cancel、event、isInteracted、listeningState、name
onStop	StopListeningEventArgs	语音识别结束时触发。参数：event、isInteracted、listeningState、name
onError	ErrorEventArgs	发生错误时触发。参数：error、errorMessage、event、name
transcriptChanged	TranscriptChangedEventArgs	转录内容更新时触发。参数：transcript、isInterimResult、event、name

方法

方法	描述
startListening()	以编程方式开始语音识别
stopListening()	以编程方式停止语音识别
destroy()	销毁组件实例并释放所有资源

故障排除

麦克风权限被拒绝

解决方案： 检查浏览器权限设置，并在安全设置中允许访问麦克风

无法识别语音

解决方案： 检查麦克风音量，清晰说话，并确认语言设置正确

组件未渲染

解决方案： 确保已导入 CSS，并已注册许可证密钥

浏览器不受支持

解决方案： 检查浏览器是否支持 Web Speech API（Chrome、Edge、Safari 均支持）

相关组件

• TextArea： 用于显示转录文本
• TextBox： 用于支持语音功能的输入字段
• Button： 用于自定义语音控制按钮
• Tooltip： 用于语音功能的上下文帮助