new RTCErrorEvent() — Methode · JavaScript-Referenz

Signatur

new RTCErrorEvent(type, options)

Beschreibung

Der Konstruktor RTCErrorEvent() erzeugt ein Ereignisobjekt vom Typ RTCErrorEvent. Solche Ereignisse lösen WebRTC-Objekte wie RTCDataChannel oder RTCDtlsTransport aus, wenn ein Fehler auftritt. Über die Eigenschaft error erreichst du ein RTCError-Objekt. Es erweitert DOMException und liefert mit errorDetail, sctpCauseCode, sdpLineNumber, receivedAlert und sentAlert genauere Angaben zur Ursache.

Normalerweise erzeugt der Browser diese Ereignisse selbst. Den Konstruktor brauchst du vor allem in drei Fällen:

Tests: In Unit- oder Integrationstests kannst du Fehlerfälle nachstellen, zum Beispiel einen abgebrochenen Datenkanal.
Eigene Abstraktionsschichten: Wenn du WebRTC-Objekte in eigene Klassen verpackst, die von EventTarget erben, kannst du Fehler im gleichen Format weitergeben.
Polyfills und Mocks: Du kannst das Verhalten nativer WebRTC-Objekte nachbilden.

Das Options-Objekt muss die Eigenschaft error enthalten. Fehlt sie, wirft der Konstruktor einen TypeError. Zusätzlich gelten die üblichen Ereignis-Optionen bubbles, cancelable und composed.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses. Bei WebRTC ist das praktisch immer `"error"`.
$options Pflicht	object		Objekt zur Initialisierung. Es erbt alle Optionen von `Event()` und hat zusätzlich eine Pflicht-Eigenschaft (siehe unten).
$options.error Pflicht	RTCError		Das `RTCError`-Objekt mit der Beschreibung des Fehlers. Ohne diese Eigenschaft wirft der Konstruktor einen `TypeError`.
$options.bubbles	boolean	false	Gibt an, ob das Ereignis im DOM nach oben weitergereicht wird.
$options.cancelable	boolean	false	Gibt an, ob sich das Ereignis mit `preventDefault()` abbrechen lässt.
$options.composed	boolean	false	Gibt an, ob das Ereignis die Grenze eines Shadow DOM überschreitet.

Rückgabewert

Typ

RTCErrorEvent

Beschreibung

Ein neues RTCErrorEvent. Seine schreibgeschützte Eigenschaft error verweist auf das übergebene RTCError.

Beispiele

Fehlerereignis erzeugen und auswerten

// RTCError mit Detailangabe erzeugen
const rtcError = new RTCError(
  { errorDetail: 'sctp-failure', sctpCauseCode: 12 },
  'SCTP-Verbindung vom Gegenüber abgebrochen'
);

const event = new RTCErrorEvent('error', { error: rtcError });

console.log(event.type);
console.log(event.error.errorDetail);
console.log(event.error.sctpCauseCode);
console.log(event.error.message);

error sctp-failure 12 SCTP-Verbindung vom Gegenüber abgebrochen

Fehler eines Datenkanals im Test nachstellen

const pc = new RTCPeerConnection();
const channel = pc.createDataChannel('chat');

channel.addEventListener('error', (e) => {
  const { errorDetail, message } = e.error;
  console.warn(`Datenkanal-Fehler (${errorDetail}): ${message}`);
});

// Fehlerfall für den Test simulieren
const error = new RTCError({ errorDetail: 'data-channel-failure' }, 'Kanal unerwartet geschlossen');
channel.dispatchEvent(new RTCErrorEvent('error', { error }));

Datenkanal-Fehler (data-channel-failure): Kanal unerwartet geschlossen

Fehler in einer eigenen Wrapper-Klasse weitergeben

class SignalingClient extends EventTarget {
  reportSdpError(lineNumber) {
    const error = new RTCError(
      { errorDetail: 'sdp-syntax-error', sdpLineNumber: lineNumber },
      `Ungültige SDP-Zeile ${lineNumber}`
    );
    this.dispatchEvent(new RTCErrorEvent('error', { error }));
  }
}

const client = new SignalingClient();
client.addEventListener('error', (e) => {
  console.log(e instanceof RTCErrorEvent, e.error.sdpLineNumber);
});
client.reportSdpError(7);

true 7

Fehlende error-Eigenschaft abfangen

try {
  new RTCErrorEvent('error', {});
} catch (err) {
  console.log(err.name);
}

TypeError

// Wichtig · Fallstricke

Browser-Unterstützung: RTCErrorEvent und RTCError gibt es in Chromium-Browsern ab Version 74 und in Safari ab 15.4. In Firefox ist die Unterstützung eingeschränkt oder fehlt je nach Version. Prüfe vor der Nutzung mit 'RTCErrorEvent' in window, ob die Klasse vorhanden ist.
options.error ist Pflicht. Ohne diese Angabe wirft der Konstruktor einen TypeError, auch wenn das Options-Objekt selbst übergeben wurde.
errorDetail ist im Konstruktor von RTCError ebenfalls Pflicht. Erlaubt sind nur bestimmte Werte, zum Beispiel \"data-channel-failure\", \"dtls-failure\", \"fingerprint-failure\", \"sctp-failure\", \"sdp-syntax-error\", \"hardware-encoder-not-available\" und \"hardware-encoder-error\". Bei einem ungültigen Wert wirft der Konstruktor einen TypeError.
Selbst erzeugte Ereignisse haben isTrusted === false. Code, der nur echte Browser-Ereignisse verarbeiten soll, kann sie daran erkennen.
Wenn du ein RTCErrorEvent auf einem echten RTCDataChannel auslöst, ändert das den Zustand des Kanals nicht. Das Ereignis erreicht nur die registrierten Listener.

Siehe auch

RTCErrorEvent RTCError RTCDataChannel RTCDtlsTransport DOMException EventTarget.prototype.dispatchEvent()