new RTCDataChannelEvent() — Methode · JavaScript-Referenz

Signatur

new RTCDataChannelEvent(type, options)

Beschreibung

Mit dem Konstruktor new RTCDataChannelEvent() erzeugen Sie ein Ereignisobjekt vom Typ RTCDataChannelEvent. Solche Ereignisse löst der Browser normalerweise selbst aus, und zwar als datachannel-Ereignis auf einer RTCPeerConnection, sobald die Gegenseite einen Datenkanal mit createDataChannel() geöffnet hat. Die Eigenschaft channel des Ereignisses verweist dann auf den neuen RTCDataChannel.

Selbst gebraucht wird der Konstruktor vor allem in Tests (zum Beispiel beim Mocken von Signalisierungsabläufen), in Wrapper-Bibliotheken, die Ereignisse an eigene EventTarget-Objekte weiterreichen, und in Polyfills. Im normalen Anwendungscode müssen Sie ihn kaum aufrufen.

Wichtig: Im Optionsobjekt muss channel immer angegeben werden und auf eine echte RTCDataChannel-Instanz zeigen. Einen RTCDataChannel können Sie nicht direkt konstruieren. Sie bekommen ihn nur über RTCPeerConnection.prototype.createDataChannel().

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses. Bei Standardverhalten ist das `"datachannel"`, aber jeder beliebige Name ist erlaubt.
$options Pflicht	RTCDataChannelEventInit		Optionsobjekt mit folgenden Feldern: `channel` (`RTCDataChannel`, Pflicht): der Datenkanal, den das Ereignis transportiert. `bubbles` (`boolean`, Standard `false`): ob das Ereignis im DOM nach oben weitergereicht wird (bubbling). `cancelable` (`boolean`, Standard `false`): ob sich das Ereignis abbrechen lässt. `composed` (`boolean`, Standard `false`): ob das Ereignis Shadow-DOM-Grenzen überschreitet.

Rückgabewert

Typ

RTCDataChannelEvent

Beschreibung

Ein neues RTCDataChannelEvent-Objekt. Seine schreibgeschützte Eigenschaft channel verweist auf den übergebenen Datenkanal.

Beispiele

Ereignis manuell erzeugen und auslösen

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

pc.addEventListener('datachannel', (event) => {
  console.log('Kanal empfangen:', event.channel.label);
});

// Künstliches datachannel-Ereignis erzeugen (z. B. für Tests)
const event = new RTCDataChannelEvent('datachannel', { channel });
pc.dispatchEvent(event);

Kanal empfangen: chat

Eigenes Ereignis in einem Wrapper weiterreichen

class ChatConnection extends EventTarget {
  constructor() {
    super();
    this.pc = new RTCPeerConnection();
    this.pc.ondatachannel = ({ channel }) => {
      // Ereignis unter eigenem Namen weiterreichen
      this.dispatchEvent(new RTCDataChannelEvent('newchannel', { channel }));
    };
  }
}

const chat = new ChatConnection();
chat.addEventListener('newchannel', (e) => {
  console.log(e instanceof RTCDataChannelEvent, e.channel.label);
});

// Simulation: Ereignis direkt auf der PeerConnection auslösen
const ch = chat.pc.createDataChannel('dateien');
chat.pc.dispatchEvent(new RTCDataChannelEvent('datachannel', { channel: ch }));

true dateien

Fehlender channel führt zu TypeError

try {
  new RTCDataChannelEvent('datachannel', {});
} catch (err) {
  console.log(err.name);
}

TypeError

// Wichtig · Fallstricke

options.channel ist Pflicht. Fehlt der Kanal oder ist es kein RTCDataChannel, wirft der Konstruktor einen TypeError.
Ereignisse, die Sie selbst mit dispatchEvent() auslösen, haben isTrusted === false. Die Verbindung selbst ändert sich dadurch nicht: Es wird kein echter Kanal ausgehandelt.
Der Konstruktor funktioniert nur in Umgebungen mit WebRTC-Unterstützung (Browser). In Node.js gibt es ihn nur über Zusatzpakete wie wrtc bzw. @roamhq/wrtc.
Alle aktuellen Browser unterstützen ihn. Sehr alte Browser mit Hersteller-Präfix (z. B. webkitRTCPeerConnection) kennen den Konstruktor unter Umständen nicht.
Viele Seiten verbieten WebRTC per Berechtigungsrichtlinie (Permissions Policy) oder in Iframes. Ohne RTCPeerConnection können Sie auch keinen Kanal für das Ereignis erzeugen.

Siehe auch

RTCDataChannelEvent RTCDataChannelEvent.channel RTCDataChannel RTCPeerConnection.prototype.createDataChannel() EventTarget.prototype.dispatchEvent() new ContentIndexEvent()