RTCDataChannel.label — Eigenschaft · JavaScript-Referenz

Signatur

RTCDataChannel.label

Beschreibung

Die Eigenschaft RTCDataChannel.label gibt eine Zeichenkette zurück, die den Datenkanal benennt. Der Wert wird beim Anlegen des Kanals als erstes Argument von RTCPeerConnection.prototype.createDataChannel(label, options) übergeben und kann danach nicht mehr geändert werden.

Der Name wird über die Verbindung an die Gegenseite übertragen. Auf dem entfernten Peer steht er deshalb im datachannel-Ereignis unter event.channel.label zur Verfügung. So kann die Anwendung eingehende Kanäle einem Zweck zuordnen, zum Beispiel "chat", "dateitransfer" oder "spielstand".

Die Eigenschaft eignet sich gut, um mehrere Kanäle über eine einzige RTCPeerConnection zu verteilen und bei eingehenden Nachrichten den passenden Handler auszuwählen. Die Bezeichnung muss nicht eindeutig sein. Mehrere Kanäle dürfen denselben Namen tragen. Eindeutig ist nur die id des Kanals.

Rückgabewert

Typ

string

Beschreibung

Der Name des Kanals, der beim Erzeugen angegeben wurde. Wurde kein Name angegeben, ist es eine leere Zeichenkette "". Die Länge ist auf 65535 Byte (UTF-8) begrenzt.

Beispiele

Label beim Erzeugen setzen und auslesen

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

console.log(chat.label);
console.log(JSON.stringify(ohneName.label));

chat ""

Eingehende Kanäle auf der Gegenseite anhand des Labels verteilen

const pc = new RTCPeerConnection();

const handler = {
  chat: (msg) => console.log('Chat:', msg),
  dateitransfer: (msg) => console.log('Datei-Chunk erhalten:', msg.byteLength ?? msg.length),
};

pc.addEventListener('datachannel', (event) => {
  const channel = event.channel;
  const verarbeite = handler[channel.label];

  if (!verarbeite) {
    console.warn(`Unbekannter Kanal: ${channel.label}`);
    channel.close();
    return;
  }

  channel.addEventListener('message', (e) => verarbeite(e.data));
});

Chat: Hallo! // sobald über den Kanal "chat" eine Nachricht eintrifft

Lokale Loopback-Verbindung: Label kommt beim Peer an

const a = new RTCPeerConnection();
const b = new RTCPeerConnection();

a.onicecandidate = (e) => e.candidate && b.addIceCandidate(e.candidate);
b.onicecandidate = (e) => e.candidate && a.addIceCandidate(e.candidate);

b.ondatachannel = ({ channel }) => {
  console.log('Empfangen:', channel.label, 'id:', channel.id);
};

a.createDataChannel('spielstand');

const offer = await a.createOffer();
await a.setLocalDescription(offer);
await b.setRemoteDescription(offer);
const answer = await b.createAnswer();
await b.setLocalDescription(answer);
await a.setRemoteDescription(answer);

Empfangen: spielstand id: 0

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie channel.label = 'neu' wird stillschweigend ignoriert. Im Strict Mode löst sie einen TypeError aus. Wenn du einen anderen Namen brauchst, musst du einen neuen Kanal anlegen.
Nicht eindeutig: Mehrere Kanäle können dasselbe Label haben. Zur eindeutigen Kennzeichnung dient RTCDataChannel.id.
Längenbegrenzung: Ist das Label in UTF-8 länger als 65535 Byte, wirft createDataChannel() einen TypeError.
Ausgehandelte Kanäle: Bei negotiated: true wird kein datachannel-Ereignis ausgelöst. Beide Seiten legen den Kanal mit derselben id selbst an. Das Label wird dabei nicht abgeglichen und sollte auf beiden Seiten gleich gewählt werden.
Sicherheit: Das Label kommt von der Gegenseite und ist deshalb eine nicht vertrauenswürdige Eingabe. Füge es nicht ungeprüft per innerHTML in die Seite ein, sonst droht XSS.
Die Eigenschaft wird von allen modernen Browsern unterstützt (Chrome, Firefox, Safari, Edge). In Node.js ist sie nur über Zusatzbibliotheken wie node-datachannel oder wrtc verfügbar.

Siehe auch

RTCDataChannel RTCPeerConnection.prototype.createDataChannel() RTCDataChannel.id RTCDataChannel.protocol RTCDataChannel.readyState MediaStreamTrack.label