syncfusion-react-speech-to-text

用途

Syncfusion React SpeechToText 组件用于在 React 应用中将用户口述的语音转换为文本，核心依赖浏览器 Web Speech API。它负责从用户麦克风采集音频，并实时完成语音到文本的转换。本技能文档帮助开发者实现、定制和排查 React 应用中的语音识别功能。

主要能力

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

环境准备与安装

文档提供 references/getting-started.md，涵盖：通过 npm 安装、包安装与设置、基础组件实现、CSS 导入与主题选择、首个可运行示例、TypeScript 配置，以及通过 disabled 属性禁用组件。

快速开始示例代码（原文保留）：

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;

语音识别特性

文档提供 references/speech-recognition-features.md，涵盖：实时获取转录文本、设置识别语言、管理临时结果（interim results）、通过 SpeechToTextState 枚举（Inactive、Listening、Stopped）管理监听状态、从事件参数和组件 ref 读取 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() 方法和基于 ref 的组件控制。

事件处理器：

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()：销毁组件实例并释放所有资源

关键属性

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 在页面重载间保持组件状态

全球化与本地化

文档提供 references/globalization-and-localization.md，涵盖：使用 L10n.load() 进行本地化、可用的区域字符串与翻译、语言特定的错误消息、RTL（从右到左）支持、无障碍标签与 ARIA 属性、用于按钮元素自定义 HTML/ARIA 属性的 htmlAttributes、多语言界面支持。

常见使用模式

模式 1：语音表单输入，将多个 SpeechToText 组件与 TextBox 组合，分别采集姓名、留言等字段（示例代码使用 handleNameTranscript / handleMessageTranscript 更新 formData）。

模式 2：编程控制，通过 useRef 引用组件并调用 startListening()、stopListening()（示例代码包含启动与停止录音按钮）。

模式 3：错误处理，通过 onError 设置错误提示（args.errorMessage 为可读描述，args.error 为错误代码），并用 onStart / onStop 更新监听状态。

故障排除与安全

文档提供 references/troubleshooting-and-security.md，涵盖：常见问题与解决方案、浏览器兼容性矩阵、麦克风权限处理、安全注意事项与最佳实践、隐私与数据传输、性能优化、离线回退策略。

列出的常见问题及解决方案：

麦克风权限被拒绝：检查浏览器权限设置，在安全设置中允许麦克风访问
无法识别语音：检查麦克风音量、清晰发音、确认语言设置正确
组件未渲染：确保已导入 CSS 并注册 license key
浏览器不支持：检查浏览器是否支持 Web Speech API（Chrome、Edge、Safari 支持）

限制

具体价格、收费模式、许可条款与平台支持范围在所提供的资料中暂未提供。浏览器兼容性的完整矩阵、离线回退的具体实现方式等细节需查阅对应参考文档。

技能介绍

用途