syncfusion-react-speech-to-text
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseSyncfusion React SpeechToText Component
Syncfusion React SpeechToText组件
Component Overview
组件概述
The SpeechToText component enables users to convert spoken words into text using the Web Speech API. This skill helps you implement, customize, and troubleshoot speech recognition in React applications. The main component that captures audio from the user's microphone and converts speech to text in real-time using browser APIs.
SpeechToText组件允许用户通过Web Speech API将语音转换为文本。本技能可帮助你在React应用中实现、自定义语音识别功能并排查相关问题。该核心组件通过浏览器API捕获用户麦克风的音频,并实时将语音转换为文本。
Key Capabilities
核心功能
- Real-time speech recognition
- Multiple language support
- Customizable button and tooltip
- Event-driven architecture
- Programmatic control via methods
- Accessibility support (ARIA labels, keyboard navigation)
- Localization support
- Error handling and recovery
- 实时语音识别
- 多语言支持
- 可自定义按钮与提示框
- 事件驱动架构
- 通过方法实现程序化控制
- 无障碍支持(ARIA标签、键盘导航)
- 本地化支持
- 错误处理与恢复
Documentation
文档资料
Getting Started
快速开始
📄 Read: references/getting-started.md
- Installation via npm
- Package installation and setup
- Basic component implementation
- CSS imports and theme selection
- First working example
- TypeScript configuration
- Disabling the component (property)
disabled
📄 阅读: references/getting-started.md
- 通过npm安装
- 包安装与配置
- 基础组件实现
- CSS导入与主题选择
- 首个可用示例
- TypeScript配置
- 禁用组件(属性)
disabled
Speech Recognition Features
语音识别功能
📄 Read: references/speech-recognition-features.md
- Retrieving transcripts in real-time
- Setting language for recognition
- Managing interim results
- Listening state management with enum (Inactive, Listening, Stopped)
SpeechToTextState - Reading from event args and component ref
listeningState - Handling speech-to-text conversion
- Real-time vs final results
📄 阅读: references/speech-recognition-features.md
- 实时获取转录文本
- 设置识别语言
- 管理临时结果
- 通过枚举管理监听状态(Inactive、Listening、Stopped)
SpeechToTextState - 从事件参数与组件ref中读取
listeningState - 处理语音转文本转换
- 实时结果与最终结果对比
Button and Tooltip Customization
按钮与提示框自定义
📄 Read: references/button-and-tooltip-customization.md
- Customizing button content and icons
- Icon positioning and styling
- Controlling tooltip visibility (property)
showTooltip - Tooltip configuration and placement (all 12 values)
TooltipPosition - CSS class styling (e-primary, e-success, etc.)
- Button appearance modes
- Responsive button design
📄 阅读: references/button-and-tooltip-customization.md
- 自定义按钮内容与图标
- 图标定位与样式设置
- 控制提示框可见性(属性)
showTooltip - 提示框配置与位置(支持全部12种取值)
TooltipPosition - CSS类样式设置(e-primary、e-success等)
- 按钮外观模式
- 响应式按钮设计
Events and Methods
事件与方法
📄 Read: references/events-and-methods.md
- Event handling (created, onStart, onStop, onError, transcriptChanged)
- Correct event argument interfaces (StartListeningEventArgs, StopListeningEventArgs, ErrorEventArgs, TranscriptChangedEventArgs)
- property to prevent listening start
cancel - to distinguish user vs programmatic triggers
isInteracted - for human-readable error details
errorMessage - for interim vs final transcript results
isInterimResult - startListening(), stopListening(), and destroy() methods
- Ref-based component control
- Programmatic listening management
📄 阅读: references/events-and-methods.md
- 事件处理(created、onStart、onStop、onError、transcriptChanged)
- 正确的事件参数接口(StartListeningEventArgs、StopListeningEventArgs、ErrorEventArgs、TranscriptChangedEventArgs)
- 属性:阻止监听启动
cancel - :区分用户触发与程序化触发
isInteracted - :人类可读的错误详情
errorMessage - :区分临时转录结果与最终转录结果
isInterimResult - startListening()、stopListening()、destroy()方法
- 基于ref的组件控制
- 程序化监听管理
Globalization and Localization
全球化与本地化
📄 Read: references/globalization-and-localization.md
- Localization with L10n.load()
- Available locale strings and translations
- Language-specific error messages
- RTL support for right-to-left languages
- Accessibility labels and ARIA attributes
- for custom HTML/ARIA attributes on the button element
htmlAttributes - Multi-language interface support
📄 阅读: references/globalization-and-localization.md
- 通过L10n.load()实现本地化
- 可用的区域字符串与翻译
- 语言特定的错误提示
- 支持从右到左(RTL)布局
- 无障碍标签与ARIA属性
- :为按钮元素添加自定义HTML/ARIA属性
htmlAttributes - 多语言界面支持
Troubleshooting and Security
故障排查与安全
📄 Read: references/troubleshooting-and-security.md
- Common issues and solutions
- Browser compatibility matrix
- Microphone permission handling
- Security considerations and best practices
- Privacy and data transmission
- Performance optimization
- Offline fallback strategies
📄 阅读: references/troubleshooting-and-security.md
- 常见问题与解决方案
- 浏览器兼容性矩阵
- 麦克风权限处理
- 安全注意事项与最佳实践
- 隐私与数据传输
- 性能优化
- 离线回退策略
Quick Start Example
快速开始示例
tsx
import { SpeechToTextComponent, TextAreaComponent, TranscriptChangedEventArgs } from '@syncfusion/ej2-react-inputs';
import { useState } from 'react';
import '@syncfusion/ej2-react-inputs/styles/material.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;tsx
import { SpeechToTextComponent, TextAreaComponent, TranscriptChangedEventArgs } from '@syncfusion/ej2-react-inputs';
import { useState } from 'react';
import '@syncfusion/ej2-react-inputs/styles/material.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;Common Patterns
常见模式
Pattern 1: Voice Form Input
模式1:语音表单输入
tsx
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>
);
}tsx
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>
);
}Pattern 2: Programmatic Control
模式2:程序化控制
tsx
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>
);
}tsx
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>
);
}Pattern 3: Error Handling
模式3:错误处理
tsx
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>
);
}tsx
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>
);
}Key Props
核心属性
| Prop | Type | Description |
|---|---|---|
| string | Language for speech recognition (e.g., 'en-US', 'fr-FR') |
| string | Current transcribed text |
| boolean | Show real-time results (default: true) |
| SpeechToTextState | Current listening state (Inactive, Listening, Stopped) |
| ButtonSettingsModel | Customize button appearance and content |
| TooltipSettingsModel | Configure tooltip display |
| boolean | Whether to display the tooltip on hover (default: true) |
| string | Apply CSS classes for styling |
| boolean | Disable all component interaction (default: false) |
| { [key: string]: string } | Additional HTML attributes (ARIA, data-*, etc.) for the root button element |
| string | Localization language code |
| boolean | Enable right-to-left layout |
| boolean | Persist component state between page reloads via localStorage |
| 属性 | 类型 | 描述 |
|---|---|---|
| string | 语音识别语言(例如:'en-US'、'fr-FR') |
| string | 当前转录文本 |
| boolean | 是否显示实时结果(默认:true) |
| SpeechToTextState | 当前监听状态(Inactive、Listening、Stopped) |
| ButtonSettingsModel | 自定义按钮外观与内容 |
| TooltipSettingsModel | 配置提示框显示 |
| boolean | 鼠标悬停时是否显示提示框(默认:true) |
| string | 应用自定义CSS类进行样式设置 |
| boolean | 禁用组件所有交互(默认:false) |
| { [key: string]: string } | 为根按钮元素添加额外HTML属性(ARIA、data-*等) |
| string | 本地化语言代码 |
| boolean | 启用从右到左布局 |
| boolean | 通过localStorage在页面刷新时保留组件状态 |
Event Handlers
事件处理器
| Event | Args | Description |
|---|---|---|
| - | Fired when component is initialized |
| StartListeningEventArgs | Fired when speech recognition begins. Args: |
| StopListeningEventArgs | Fired when speech recognition ends. Args: |
| ErrorEventArgs | Fired when an error occurs. Args: |
| TranscriptChangedEventArgs | Fired when transcription updates. Args: |
| 事件 | 参数 | 描述 |
|---|---|---|
| - | 组件初始化完成时触发 |
| StartListeningEventArgs | 语音识别开始时触发。参数: |
| StopListeningEventArgs | 语音识别结束时触发。参数: |
| ErrorEventArgs | 发生错误时触发。参数: |
| TranscriptChangedEventArgs | 转录内容更新时触发。参数: |
Methods
方法
| Method | Description |
|---|---|
| Begin speech recognition programmatically |
| Stop speech recognition programmatically |
| Destroy the component instance and release all resources |
| 方法 | 描述 |
|---|---|
| 程序化启动语音识别 |
| 程序化停止语音识别 |
| 销毁组件实例并释放所有资源 |
Troubleshooting
故障排查
Microphone permission denied
麦克风权限被拒绝
Solution: Check browser permissions settings and allow microphone access in security settings
解决方案: 检查浏览器权限设置,在安全设置中允许麦克风访问
Speech not recognized
语音无法被识别
Solution: Check microphone volume, speak clearly, verify correct language setting
解决方案: 检查麦克风音量、清晰发音、验证语言设置是否正确
Component not rendering
组件无法渲染
Solution: Ensure CSS imports are included and license key is registered
解决方案: 确保已导入CSS文件并注册许可证密钥
Browser not supported
浏览器不支持
Solution: Check if browser supports Web Speech API (Chrome, Edge, Safari support it)
解决方案: 检查浏览器是否支持Web Speech API(Chrome、Edge、Safari均支持)
Related Components
相关组件
- TextArea: For displaying transcribed text
- TextBox: For input fields with voice capabilities
- Button: For custom voice control buttons
- Tooltip: For contextual help on voice features
- TextArea: 用于显示转录文本
- TextBox: 具备语音输入功能的输入框
- Button: 自定义语音控制按钮
- Tooltip: 为语音功能提供上下文帮助