syncfusion-javascript-speech-to-text

Syncfusion JavaScript SpeechToText 组件

概述

Syncfusion JavaScript SpeechToText 组件是一种基于按钮的控件，点击后即可启动语音识别。它会从用户的麦克风采集音频，通过浏览器的语音识别服务进行处理，并通过事件和属性提供转录文本。

主要功能：

• 实时语音转录，支持中间结果和最终结果
• 可配置语言支持（en-US、fr-FR、de-DE 等）
• 可自定义按钮外观、图标和内容
• 配置启动和停止状态的工具提示
• 事件驱动架构（onStart、onStop、onError、transcriptChanged）
• 通过 startListening() 和 stopListening() 方法进行程序化控制
• 支持 14 种以上 UI 文本键的本地化
• 支持 RTL（从右向左）布局
• 处理 8 种常见语音识别错误
• 语音数据隐私的安全注意事项

文档和导航指南

开始使用

📄 阅读： references/getting-started.md

从这里开始进行初始设置和基本实现：

• 安装依赖项（@syncfusion/ej2-inputs）
• 设置开发环境
• 导入 CSS 样式和主题
• 创建基本的 SpeechToText 按钮
• 为启动/停止状态添加按钮内容
• 处理 transcriptChanged 事件
• 运行第一个语音识别示例

语音识别功能

📄 阅读： references/speech-recognition.md

语音识别的核心功能和配置：

• 获取语音音频的转录文本
• 设置识别语言（lang 属性）
• 允许中间结果，或仅接收最终结果
• 管理监听状态（Inactive、Listening、Stopped）
• 显示或隐藏工具提示
• 禁用组件
• 在按钮元素上设置 HTML 属性
• 处理 8 种错误类型（no-speech、audio-capture、not-allowed 等）
• 浏览器支持矩阵和兼容性

事件

📄 阅读： references/events.md

处理语音识别生命周期中的事件：

• created 事件 — 组件初始化完成
• onStart 事件 — 语音识别开始（StartListeningEventArgs）
• onStop 事件 — 语音识别停止（StopListeningEventArgs）
• onError 事件 — 识别过程中发生错误（ErrorEventArgs）
• transcriptChanged 事件 — 转录文本更新（TranscriptChangedEventArgs）
• 事件配置示例和模式

方法

📄 阅读： references/methods.md

以编程方式控制语音识别：

• startListening() — 以编程方式启动语音识别
• stopListening() — 以编程方式终止语音识别
• 将方法与自定义按钮和控件结合使用
• 方法使用模式和最佳实践

外观自定义

📄 阅读： references/appearance.md

自定义按钮和工具提示的外观：

• 按钮内容（content、stopContent 属性）
• 按钮图标（iconCss、stopIconCss 属性）
• 图标位置（top、bottom、left、right）
• 主按钮样式（isPrimary 属性）
• 工具提示内容和位置
• 应用 CSS 类（e-primary、e-outline、e-info、e-success、e-warning、e-danger）
• 使用 cssClass 属性自定义样式

全球化

📄 阅读： references/globalization.md

本地化和国际化支持：

• 使用 L10n.load 方法进行本地化
• 默认文本标识符（用于错误消息、工具提示和 ARIA 标签的 14 个键）
• 配置 locale 属性
• 使用 enableRtl 属性支持 RTL（从右向左）
• 为阿拉伯语、希伯来语、波斯语实现 RTL 布局

安全注意事项

📄 阅读： references/security.md

安全与隐私最佳实践：

• 在线依赖要求
• 潜在安全风险（数据传输、隐私、中间人攻击）
• 浏览器权限漏洞利用
• 缓解策略（HTTPS、可信环境、明确同意）
• 第三方服务的数据处理

快速入门示例

import { SpeechToText, TextArea, TranscriptChangedEventArgs } from "@syncfusion/ej2-inputs";

// Initialize SpeechToText component
const speechToText: SpeechToText = new SpeechToText({
    transcriptChanged: (args: TranscriptChangedEventArgs) => {
        // Update textarea with transcribed text
        textareaObj.value = args.transcript;
    }
});

// Render the component
speechToText.appendTo('#speechtotext_default');

// Create textarea for displaying transcription
const textareaObj: TextArea = new TextArea({
    rows: 5,
    cols: 50,
    value: '',
    resizeMode: 'None',
    placeholder: 'Transcribed text will be shown here...'
});
textareaObj.appendTo('#textareaInst');

<!DOCTYPE html>
<html lang="en">
<head>
    <title>SpeechToText Example</title>
    <link href="https://cdn.syncfusion.com/ej2/32.1.19/ej2-base/styles/fluent2.css" rel="stylesheet" />
    <link href="https://cdn.syncfusion.com/ej2/32.1.19/ej2-buttons/styles/fluent2.css" rel="stylesheet" />
    <link href="https://cdn.syncfusion.com/ej2/32.1.19/ej2-popups/styles/fluent2.css" rel="stylesheet" />
    <link href="https://cdn.syncfusion.com/ej2/32.1.19/ej2-inputs/styles/fluent2.css" rel="stylesheet" />
</head>
<body>
    <div id="container">
        <button id="speechtotext_default"></button>
        <textarea id="textareaInst"></textarea>
    </div>
</body>
</html>

常见模式

模式 1：支持语言设置的自定义按钮

const speechToText: SpeechToText = new SpeechToText({
    lang: 'fr-FR', // French language recognition
    buttonSettings: {
        content: 'Commencer',
        stopContent: 'Arrêter',
        isPrimary: true
    },
    transcriptChanged: (args: TranscriptChangedEventArgs) => {
        console.log('Transcript:', args.transcript);
    }
});
speechToText.appendTo('#speechtotext');

适用场景： 需要识别特定语言语音的国际化应用。

模式 2：事件驱动的状态管理

const speechToText: SpeechToText = new SpeechToText({
    onStart: (args: StartListeningEventArgs) => {
        console.log('Started listening, state:', args.listeningState);
        // Update UI to show listening indicator
    },
    onStop: (args: StopListeningEventArgs) => {
        console.log('Stopped listening, state:', args.listeningState);
        // Update UI to hide listening indicator
    },
    onError: (args: ErrorEventArgs) => {
        console.error('Speech recognition error:', args.error);
        // Show error message to user
    },
    transcriptChanged: (args: TranscriptChangedEventArgs) => {
        // Real-time transcript updates
        document.getElementById('output').textContent = args.transcript;
    }
});
speechToText.appendTo('#speechtotext');

适用场景： 需要在语音识别过程中提供视觉反馈和错误处理的应用。

模式 3：通过自定义触发器进行编程控制

const speechToText: SpeechToText = new SpeechToText({
    transcriptChanged: (args: TranscriptChangedEventArgs) => {
        textArea.value = args.transcript;
    }
});
speechToText.appendTo('#speechtotext');

// Start listening when form field gains focus
document.getElementById('inputField').addEventListener('focus', () => {
    speechToText.startListening();
});

// Stop listening when form field loses focus
document.getElementById('inputField').addEventListener('blur', () => {
    speechToText.stopListening();
});

适用场景： 将语音识别集成到自定义 UI 元素或表单工作流中。

模式 4：仅获取最终结果（无中间结果）

const speechToText: SpeechToText = new SpeechToText({
    allowInterimResults: false, // Only final results
    transcriptChanged: (args: TranscriptChangedEventArgs) => {
        // Transcript only updates when recognition is complete
        textArea.value = args.transcript;
    }
});
speechToText.appendTo('#speechtotext');

适用场景： 需要获取完整句子或短语，而非实时逐词转录的应用。

主要属性

属性	类型	描述	默认值
transcript	string	获取或设置转录文本	''
lang	string	识别语言（例如，'en-US'、'fr-FR'）	'en-US'
allowInterimResults	boolean	启用实时中间结果	true
listeningState	SpeechToTextState	当前状态（Inactive、Listening、Stopped）	Inactive
showTooltip	boolean	鼠标悬停在按钮上时显示工具提示	true
disabled	boolean	禁用组件	false
enablePersistence	boolean	在页面重新加载后保留组件状态	false
buttonSettings	ButtonSettingsModel	按钮自定义选项	{}
tooltipSettings	TooltipSettingsModel	工具提示自定义选项	{}
cssClass	string	用于设置样式的自定义 CSS 类	''
locale	string	本地化区域设置（例如，'en-US'、'de'）	'en-US'
enableRtl	boolean	启用从右到左布局	false

常见用例

用例 1：支持语音输入的表单

允许用户通过语音输入而非打字来填写表单字段，从而提升数据录入任务的无障碍性和速度。

用例 2：实时转录应用

构建笔记记录或会议转录应用，支持语言设置，并将语音实时转换为文本。

用例 3：语音命令界面

实现语音命令识别，根据语音关键词控制应用功能、进行导航或触发操作。

用例 4：提升无障碍体验

为行动不便、无法轻松使用键盘打字的用户提供语音输入替代方式。

用例 5：多语言支持

为全球化应用提供多种语言的语音识别支持，让用户能够使用偏好的语言进行语音输入。

用例 6：语音搜索功能

为应用添加语音搜索功能，让用户能够通过说出查询内容而非打字来搜索内容。

最佳实践

1. 始终妥善处理错误 - 实现 onError 事件，以捕获麦克风访问、网络问题或浏览器不受支持等错误，并显示对用户友好的错误消息。

2. 明确请求权限 - 在触发语音识别前，告知用户为何需要访问麦克风，以提升用户信任度和权限授予率。

3. 在生产环境中使用 HTTPS - 语音识别需要安全上下文；请确保应用通过 HTTPS 提供服务，以避免安全错误。

4. 提供视觉反馈 - 利用监听状态事件，让用户了解组件当前正在聆听、已停止还是未激活。

5. 检查浏览器兼容性 - 确认浏览器支持情况（Chrome 25+、Edge 79+、Safari 12+），并为不受支持的浏览器提供备用 UI。

6. 配置合适的语言 - 将 lang 属性设为符合用户预期的语言，以提高识别准确率。

7. 考虑中间结果 - 根据使用场景，设置 allowInterimResults:true 以提供实时反馈，或设置为 false 以仅获取最终结果。

8. 实施隐私声明 - 告知用户，语音数据可能会由第三方服务（Google、Microsoft）处理，以进行语音识别。

相关组件

• TextArea - 常与其搭配使用，以显示转录文本
• Button - 提供基础按钮功能
• Tooltip - 用于在悬停时显示帮助文本

浏览器支持

浏览器	支持的版本
Chrome	25+
Edge	79+
Firefox	不支持
Safari	12+
Opera	30+