new SpeechRecognitionErrorEvent() — Methode · JavaScript-Referenz

Signatur

new SpeechRecognitionErrorEvent(type, options)

Beschreibung

Mit dem Konstruktor SpeechRecognitionErrorEvent() erzeugen Sie selbst ein Fehler-Event der Web Speech API. Normalerweise löst der Browser dieses Event selbst an einer SpeechRecognition-Instanz aus, wenn etwas schiefgeht. Das ist zum Beispiel der Fall, wenn kein Mikrofon da ist, der Nutzer die Berechtigung verweigert oder das Netzwerk ausfällt.

Einen eigenen Aufruf des Konstruktors brauchen Sie vor allem in diesen Fällen:

Tests: Sie können Fehlerfälle in Unit- oder Integrationstests nachstellen, ohne dass Mikrofon oder Spracherkennungsdienst tatsächlich einen Fehler liefern.
Eigene Wrapper: Sie können Fehler in einer eigenen Abstraktion (z. B. einem Sprachsteuerungs-Modul auf Basis von EventTarget) im gleichen Format weitergeben wie der Browser.
Polyfills und Mocks: Sie können das Verhalten der API in Umgebungen nachbilden, die sie nicht unterstützen.

Das erzeugte Event hat die schreibgeschützten Eigenschaften error (Fehlercode als Zeichenkette) und message (Beschreibung als Text). Außerdem erbt es alle Eigenschaften von Event. Ein selbst erzeugtes Event wird erst ausgelöst, wenn Sie es mit dispatchEvent() versenden. Dabei ist isTrusted immer false.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Events. In der Regel `"error"`. So heißt das Event, das an `SpeechRecognition` ausgelöst wird.
$options Pflicht	Object		Wörterbuch mit Einstellungen für das Event. Neben den Event-Optionen `bubbles`, `cancelable` und `composed` (jeweils Standard `false`) gibt es diese Felder:
$options.error Pflicht	string		Fehlercode. Er muss ein Wert der Aufzählung `SpeechRecognitionErrorCode` sein: `"no-speech"`, `"aborted"`, `"audio-capture"`, `"network"`, `"not-allowed"`, `"service-not-allowed"`, `"language-not-supported"` (in älteren Implementierungen `"bad-grammar"`).
$options.message	string	""	Beschreibung des Fehlers als Text, gedacht für Entwickler und Logs.

Rückgabewert

Typ

SpeechRecognitionErrorEvent

Beschreibung

Ein neues SpeechRecognitionErrorEvent-Objekt. Es hat die übergebenen Werte in type, error und message.

Beispiele

Event erzeugen und Eigenschaften lesen

// Mit Fallback auf die Version mit Präfix (ältere Chromium-Versionen)
const ErrorEventCtor = window.SpeechRecognitionErrorEvent ?? window.webkitSpeechRecognitionErrorEvent;

const event = new ErrorEventCtor('error', {
  error: 'not-allowed',
  message: 'Mikrofonzugriff wurde verweigert'
});

console.log(event.type, event.error, event.message, event.isTrusted);

error not-allowed Mikrofonzugriff wurde verweigert false

Fehlerbehandlung einer SpeechRecognition testen

const Recognition = window.SpeechRecognition ?? window.webkitSpeechRecognition;
const ErrorEventCtor = window.SpeechRecognitionErrorEvent ?? window.webkitSpeechRecognitionErrorEvent;

const recognition = new Recognition();
recognition.lang = 'de-DE';

const userMessages = {
  'no-speech': 'Es wurde keine Sprache erkannt. Bitte erneut versuchen.',
  'audio-capture': 'Kein Mikrofon gefunden.',
  'not-allowed': 'Bitte erlauben Sie den Mikrofonzugriff.',
  network: 'Netzwerkfehler – bitte Verbindung prüfen.'
};

recognition.addEventListener('error', (e) => {
  console.warn(userMessages[e.error] ?? `Unbekannter Fehler: ${e.error}`);
});

// Netzwerkfehler nachstellen, ohne echte Erkennung zu starten
recognition.dispatchEvent(new ErrorEventCtor('error', { error: 'network' }));

Netzwerkfehler – bitte Verbindung prüfen.

Fehler in einem eigenen Sprach-Wrapper weitergeben

const ErrorEventCtor = window.SpeechRecognitionErrorEvent ?? window.webkitSpeechRecognitionErrorEvent;

class VoiceCommands extends EventTarget {
  fail(code, message = '') {
    this.dispatchEvent(new ErrorEventCtor('error', { error: code, message }));
  }
}

const voice = new VoiceCommands();
voice.addEventListener('error', ({ error, message }) => {
  console.log(`[Sprachsteuerung] ${error}: ${message || '(keine Details)'}`);
});

voice.fail('language-not-supported', 'de-CH wird nicht unterstützt');

[Sprachsteuerung] language-not-supported: de-CH wird nicht unterstützt

// Wichtig · Fallstricke

Browser-Unterstützung: Firefox unterstützt die Spracherkennung der Web Speech API standardmäßig nicht. Ältere Chromium-Versionen stellen den Konstruktor nur als webkitSpeechRecognitionErrorEvent bereit. Prüfen Sie deshalb vorher, ob er vorhanden ist, und sehen Sie einen Fallback vor.
Pflichtfeld error: Fehlt options.error oder ist es kein gültiger Wert aus SpeechRecognitionErrorCode, wirft der Konstruktor einen TypeError. Eigene Fehlercodes sind nicht möglich. Für diesen Zweck ist ein CustomEvent besser geeignet.
Kein echter Fehler: Ein selbst ausgelöstes Event beendet keine laufende Erkennung und löst auch kein end-Event aus. Es ruft nur die registrierten Listener auf. isTrusted ist dabei immer false.
Hinweis zu message: Der Inhalt ist nicht einheitlich festgelegt und hängt vom Browser ab. Zeigen Sie ihn Nutzern nicht direkt an. Werten Sie stattdessen error aus.
Datenschutz: Chrome schickt Audiodaten zur Erkennung an einen Server. Ohne Netzwerkverbindung tritt daher häufig der Fehler \"network\" auf.

Siehe auch

new GPUUncapturedErrorEvent() new SpeechRecognitionEvent() new SpeechRecognitionPhrase() new SpeechRecognition() new SpeechSynthesisErrorEvent()