RTCDataChannelEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface RTCDataChannelEvent extends Event

Beschreibung

RTCDataChannelEvent ist der Ereignistyp, den eine RTCPeerConnection beim Event datachannel auslöst. Das passiert, wenn die entfernte Gegenstelle mit createDataChannel() einen neuen Datenkanal anlegt und dieser über die bestehende Verbindung ausgehandelt wurde. Die einzige zusätzliche Eigenschaft ist channel, also der neue RTCDataChannel.

Man braucht das Interface immer auf der empfangenden Seite einer WebRTC-Verbindung: Der Initiator ruft pc.createDataChannel("chat") auf, und der andere Peer bekommt den Kanal über pc.ondatachannel oder pc.addEventListener("datachannel", …). Im Handler registriert man dann open-, message- und close-Listener auf event.channel.

Auch wenn der Kanal im Event schon vorhanden ist, muss sein readyState noch nicht "open" sein. Wer Nachrichten senden will, wartet am besten auf das open-Event des Kanals. Für Kanäle mit negotiated: true (die ausgehandelte Kanal-ID wird auf beiden Seiten manuell vergeben) wird kein datachannel-Event ausgelöst.

Mit dem Konstruktor new RTCDataChannelEvent(type, { channel }) kann man ein solches Event auch selbst erzeugen, z. B. für Tests. Im normalen Betrieb erzeugt der Browser das Event.

Rückgabewert

Typ

RTCDataChannelEvent

Beschreibung

Der Konstruktor gibt ein neues RTCDataChannelEvent zurück, dessen Eigenschaft channel auf den übergebenen RTCDataChannel verweist.

Beispiele

Eingehenden Datenkanal mit addEventListener annehmen

const pc = new RTCPeerConnection();

pc.addEventListener("datachannel", (event) => {
  const { channel } = event; // RTCDataChannelEvent.channel
  console.log(`Neuer Kanal: ${channel.label}`);

  channel.addEventListener("open", () => channel.send("Hallo zurück!"));
  channel.addEventListener("message", (e) => console.log("Empfangen:", e.data));
  channel.addEventListener("close", () => console.log("Kanal geschlossen"));
});

Neuer Kanal: chat Empfangen: Hallo!

Vollständiges lokales Beispiel mit zwei Peers und ondatachannel

const sender = new RTCPeerConnection();
const receiver = new RTCPeerConnection();

// ICE-Kandidaten direkt austauschen (lokal, ohne Signalisierungsserver)
sender.onicecandidate = ({ candidate }) => candidate && receiver.addIceCandidate(candidate);
receiver.onicecandidate = ({ candidate }) => candidate && sender.addIceCandidate(candidate);

// Empfangsseite: on-Property statt addEventListener
receiver.ondatachannel = (event) => {
  console.log(event instanceof RTCDataChannelEvent); // true
  event.channel.onmessage = (e) => console.log("Empfänger erhielt:", e.data);
};

const chat = sender.createDataChannel("chat");
chat.onopen = () => chat.send("Hallo!");

const run = async () => {
  const offer = await sender.createOffer();
  await sender.setLocalDescription(offer);
  await receiver.setRemoteDescription(offer);
  const answer = await receiver.createAnswer();
  await receiver.setLocalDescription(answer);
  await sender.setRemoteDescription(answer);
};

run();

true Empfänger erhielt: Hallo!

Event manuell erzeugen (z. B. für Tests)

const pc = new RTCPeerConnection();
const channel = pc.createDataChannel("test");

const evt = new RTCDataChannelEvent("datachannel", { channel });

pc.addEventListener("datachannel", (e) => {
  console.log(e.type, e.channel.label);
});

pc.dispatchEvent(evt);

datachannel test

// Wichtig · Fallstricke

Nur auf der Gegenseite: Das Event wird ausgelöst, wenn der entfernte Peer einen Kanal anlegt. Ein lokal mit createDataChannel() angelegter Kanal löst lokal kein datachannel aus.
Ausgehandelte Kanäle: Bei createDataChannel(label, { negotiated: true, id }) gibt es gar kein datachannel-Event. Beide Seiten müssen den Kanal dann selbst mit derselben id anlegen.
Handler früh registrieren: Den datachannel-Listener direkt nach dem Anlegen der RTCPeerConnection setzen, also vor setRemoteDescription(). Sonst kann das Event verpasst werden.
readyState prüfen: event.channel.readyState kann noch "connecting" sein. Ein send() vor open wirft einen InvalidStateError.
Sicherheit: Daten, die über den Kanal ankommen, stammen von einem fremden Peer. Sie sollten wie jede Nutzereingabe geprüft werden, z. B. niemals ungeprüft in innerHTML schreiben.
Kompatibilität: Wird von allen modernen Browsern unterstützt. In Node.js gibt es das Interface nicht von Haus aus, dafür braucht man Bibliotheken wie wrtc oder node-datachannel.

Siehe auch

RTCDataChannel RTCPeerConnection RTCPeerConnection.prototype.createDataChannel() RTCDataChannelEvent.channel Event TaskPriorityChangeEvent