syncfusion-angular-speech-to-text

Syncfusion Angular SpeechToText 组件

组件概述

Syncfusion Angular SpeechToText 组件是一款轻量、易于访问的控件，可使用浏览器原生的语音识别 API 将语音转换为文本。

主要功能：

• 实时转录 - 将语音转换为文本，并提供中间结果和最终结果
• 按钮自定义 - 配置开始/停止按钮的图标、文本、位置和样式
• 工具提示支持 - 添加自定义内容和位置的工具提示，提升用户体验
• 事件与交互 - 处理聆听状态变化、错误和转录文本更新
• 方法 - 通过 startListening() 和 stopListening() 方法进行编程控制
• 语言支持 - 通过区域设置配置实现多语言识别
• 全球化 - 为国际化应用提供 RTL 支持和本地化
• 样式选项 - CSS 类、HTML 属性和主题集成
• 安全功能 - 强制使用 HTTPS，并明确授予麦克风权限
• 浏览器兼容性 - Chrome 25+、Edge 79+、Safari 12+、Opera 30+

文档和导航指南

开始使用

📄 阅读： references/getting-started.md

• 软件包安装（Ivy 与 ngcc 兼容性）
• Angular 项目设置和配置
• CSS 导入和主题管理
• 模块导入和基本组件渲染
• 按钮内容自定义
• 与 TextArea 集成的完整示例

按钮自定义

📄 阅读： references/button-customization.md

• ButtonSettingsModel 配置
• 开始和停止按钮的内容标签
• 使用 CSS 类自定义图标
• 图标位置（上、下、左、右）
• 使用主要按钮样式突出显示
• 视觉样式变化和最佳实践

工具提示配置

📄 阅读： references/tooltip-configuration.md

• TooltipSettingsModel 设置
• 开始和停止状态的工具提示内容
• 工具提示相对于按钮的位置
• 启用和禁用工具提示
• 实用的工具提示使用模式

样式和外观

📄 阅读： references/styling-and-appearance.md

• CSS 类系统（e-primary、e-outline、e-info、e-success、e-warning、e-danger）
• 使用 cssClass 属性自定义样式
• 主题配置和集成
• HTML 属性自定义
• 自定义 CSS 示例和高级样式设置

事件和方法

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

• 事件类型（created、onStart、onStop、onError、transcriptChanged）
• 事件处理程序实现和事件参数（包括 event、name 属性）
• 使用 startListening()、stopListening() 和 destroy() 方法进行编程控制
• 使用 listeningState 属性（Inactive、Listening、Stopped）控制组件状态
• 使用 onStart 事件中的 cancel 属性取消聆听
• 使用 isInteracted 属性区分用户操作和编程操作
• 适用于不同场景的事件处理模式
• 以编程方式管理聆听生命周期
• 状态转换管理和工作流控制
• 组件清理和内存管理

语音识别功能

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

• 获取语音输入的转录文本
• 设置识别语言（lang 属性）
• 中间结果配置（allowInterimResults）
• 聆听状态管理（Inactive、Listening、Stopped）
• 工具提示可见性控制（showTooltip）
• 禁用状态配置
• 使用 enablePersistence 属性持久化状态
• 状态监控和状态管理
• 使用 localStorage 自定义状态管理

国际化

📄 阅读： references/internationalization.md

• 使用 L10n.load() 配置本地化
• 错误消息和标签的翻译键映射
• 多语言实现示例
• 启用 RTL（从右到左）支持
• 语言特定配置的最佳实践

安全与错误处理

📄 阅读： references/security-and-error-handling.md

• 安全风险与缓解策略
• 数据传输与隐私问题
• 强制使用 HTTPS 并防止 MITM
• 麦克风权限管理
• 错误类型处理（no-speech、aborted、audio-capture、not-allowed、service-not-allowed、network、unsupported-browser、default）
• 浏览器支持矩阵与兼容性

快速入门示例

以下是一个最精简的可运行 SpeechToText 组件示例，包含转录文本输出：

import { Component, ViewChild } from '@angular/core';
import { SpeechToTextModule, TextAreaComponent, TextAreaModule, TranscriptChangedEventArgs } from '@syncfusion/ej2-angular-inputs';

@Component({
    imports: [SpeechToTextModule, TextAreaModule],
    standalone: true,
    selector: 'app-root',
    template: `
    <div class="speechText-container">
        <button ejs-speechtotext 
                (transcriptChanged)="onTranscriptChange($event)">
        </button>
        <ejs-textarea #outputTextarea 
                      id="textareaInst" 
                      value="" 
                      rows="5" 
                      cols="50" 
                      resizeMode="None" 
                      placeholder="Transcribed text will be shown here...">
        </ejs-textarea>
    </div>`
})
export class AppComponent {
    @ViewChild('outputTextarea') outputTextarea!: TextAreaComponent;
    
    onTranscriptChange(args: TranscriptChangedEventArgs): void {
        this.outputTextarea.value = args.transcript;
    }
}

常见模式

模式 1：自定义带事件的按钮

实现带有自定义标签和事件处理程序的样式化按钮：

public buttonSettings: ButtonSettingsModel = {
    content: 'Start Listening',
    stopContent: 'Stop Listening',
    iconCss: 'e-icons e-play',
    stopIconCss: 'e-icons e-pause',
    isPrimary: true
};

onListeningStart(args: StartListeningEventArgs): void {
    console.log('Listening started');
}

onListeningStop(args: StopListeningEventArgs): void {
    console.log('Listening stopped');
}

模式 2：多语言支持

为国际化应用配置本地化：

L10n.load({
    'de': {
        "speech-to-text": {
            "startAriaLabel": "Drücken Sie, um zu sprechen",
            "stopAriaLabel": "Drücken Sie, um zu stoppen",
            "noSpeechError": "Keine Sprache erkannt"
        }
    }
});

模式 3：以编程方式控制

无需点击用户按钮，即可通过编程方式管理聆听状态：

@ViewChild('speechtotext') speechToText!: SpeechToTextComponent;

public startListening(): void {
    this.speechToText.startListening();
}

public stopListening(): void {
    this.speechToText.stopListening();
}

模式 4：错误处理

妥善处理语音识别错误：

onErrorHandler(args: ErrorEventArgs): void {
    if (args.error === 'no-speech') {
        console.log('No speech detected. Please try again.');
    } else if (args.error === 'not-allowed') {
        console.log('Microphone permission denied.');
    }
}

模式 5：使用 cancel 条件性聆听

使用 cancel 属性控制何时可以开始聆听：

onListeningStart(args: StartListeningEventArgs): void {
    // Cancel listening if conditions aren't met
    if (!this.hasPermission || !navigator.onLine) {
        args.cancel = true;
        alert('Cannot start listening. Check permissions and connection.');
        return;
    }
    
    // Track if user or system triggered the action
    if (args.isInteracted) {
        console.log('User clicked the button');
    } else {
        console.log('Started programmatically');
    }
}

模式 6：区分临时结果与最终结果

以不同方式处理临时转录文本和最终转录文本：

onTranscriptChange(args: TranscriptChangedEventArgs): void {
    if (args.isInterimResult) {
        // Show interim results in real-time (lighter styling)
        this.interimText = args.transcript;
    } else {
        // Process final results (save, send to API, etc.)
        this.finalText = args.transcript;
        this.saveTranscript(args.transcript);
    }
}

模式 7：控制组件状态

以编程方式控制组件的运行状态：

import { SpeechToTextState } from '@syncfusion/ej2-angular-inputs';

export class AppComponent {
    public currentState: SpeechToTextState = SpeechToTextState.Inactive;
    
    // Set component to listening state
    startListening(): void {
        this.currentState = SpeechToTextState.Listening;
    }
    
    // Set component to stopped state
    stopListening(): void {
        this.currentState = SpeechToTextState.Stopped;
    }
    
    // Reset to inactive state
    resetState(): void {
        this.currentState = SpeechToTextState.Inactive;
    }
}

模式 8：正确清理组件

确保正确清理，以防止内存泄漏：

import { OnDestroy } from '@angular/core';

export class AppComponent implements OnDestroy {
    @ViewChild('speechtotext') speechToText!: SpeechToTextComponent;
    
    ngOnDestroy(): void {
        if (this.speechToText) {
            this.speechToText.stopListening();
            this.speechToText.destroy();
        }
    }
}

主要属性

属性	类型	默认值	用途
buttonSettings	ButtonSettingsModel	-	配置按钮外观和标签
tooltipSettings	TooltipSettingsModel	-	自定义工具提示内容和位置
lang	string	'en-US'	设置语音识别语言
allowInterimResults	boolean	true	启用实时临时转录
transcript	string	''	当前识别的文本（只读）
listeningState	SpeechToTextState	Inactive	监控聆听状态（Inactive、Listening、Stopped）
showTooltip	boolean	true	悬停时显示工具提示
disabled	boolean	false	禁用组件交互
enablePersistence	boolean	false	在页面重新加载后保留组件状态
enableRtl	boolean	false	启用从右到左的文本方向
cssClass	string	-	应用自定义 CSS 类
htmlAttributes	object	-	为按钮设置自定义 HTML 属性
locale	string	'en-US'	设置 UI 本地化语言

浏览器要求

SpeechToText 组件要求：

• 有效的互联网连接，用于语音识别处理
• 浏览器支持 Speech Recognition API：
  • Chrome 25+
  • Edge 79+
  • Safari 12+
  • Opera 30+
  • Firefox：不支持
• 已连接到系统的麦克风硬件
• 已在浏览器设置中授予用户麦克风权限
• HTTPS 环境，以安全访问麦克风（推荐）