Signatur
Beschreibung
Das Interface PresentationConnectionAvailableEvent gehört zur Presentation API. Mit dieser API zeigt eine Webseite (der Controller) Inhalte auf einem zweiten Bildschirm an, etwa auf einem Beamer, einem Chromecast oder einem angeschlossenen Monitor. Das Event heißt connectionavailable und wird auf einem PresentationRequest ausgelöst, sobald eine mit diesem Request verknüpfte Verbindung hergestellt ist. Auf der Empfängerseite wird es auf einer PresentationConnectionList ausgelöst, wenn sich ein neuer Controller verbindet.
Neben den geerbten Eigenschaften von Event hat das Interface eine einzige eigene Eigenschaft: connection. Sie ist schreibgeschützt und enthält die neue PresentationConnection. Über dieses Objekt sendest du Nachrichten mit send(), empfängst sie über das Event message und beendest die Präsentation mit terminate() oder close().
Das Event ist besonders nützlich, wenn Präsentationen automatisch gestartet werden: Ein Browser kann eine Präsentation über PresentationRequest als Standard-Präsentation auch ohne Aufruf von start() öffnen, etwa über das Browsermenü „Streamen…“. Dann bekommst du die Verbindung nur über dieses Event. Üblich ist deshalb, die gesamte Verbindungslogik zentral im Handler für connectionavailable zu erledigen. Ob die Verbindung über start(), reconnect() oder über den Browser entstanden ist, spielt dann keine Rolle.
Du registrierst den Handler mit addEventListener("connectionavailable", handler) oder über die Eigenschaft onconnectionavailable. Den Konstruktor brauchst du im Alltag kaum. Er ist vor allem für Tests und Polyfills da.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $type Pflicht | string | Parameter des Konstruktors new PresentationConnectionAvailableEvent(type, options): der Name des Events, in der Praxis immer "connectionavailable". |
|
| $options Pflicht | Object | Wörterbuch mit Optionen. Zusätzlich zu den Optionen von Event (bubbles, cancelable, composed) ist das Feld connection hier Pflicht. |
|
| $options.connection Pflicht | PresentationConnection | Die Verbindung, die im Event übergeben werden soll. Sie steht später in der Eigenschaft event.connection. |
Rückgabewert
connection (schreibgeschützt, Typ PresentationConnection).Beispiele
Controller: Verbindung zentral über connectionavailable annehmen
// Seite, die auf dem zweiten Bildschirm angezeigt wird
const request = new PresentationRequest(['/slides/receiver.html']);
// Als Standard-Präsentation registrieren (Browsermenü „Streamen…“)
navigator.presentation.defaultRequest = request;
request.addEventListener('connectionavailable', (event) => {
const connection = event.connection;
console.log('Neue Verbindung:', connection.id, connection.state);
connection.addEventListener('connect', () => {
connection.send(JSON.stringify({ cmd: 'goto', slide: 1 }));
});
connection.addEventListener('message', (e) => {
console.log('Antwort vom Empfänger:', e.data);
});
});
// Präsentation per Klick starten (start() braucht eine Nutzeraktion)
document.querySelector('#present').addEventListener('click', async () => {
try {
await request.start(); // löst zusätzlich connectionavailable aus
} catch (err) {
console.warn('Präsentation abgebrochen:', err.name);
}
});Empfänger: neue Controller über die PresentationConnectionList erkennen
// Läuft in receiver.html auf dem Präsentationsbildschirm
const setupConnection = (connection) => {
connection.addEventListener('message', (e) => {
const msg = JSON.parse(e.data);
console.log('Befehl erhalten:', msg.cmd);
connection.send(JSON.stringify({ ok: true }));
});
};
const list = await navigator.presentation.receiver.connectionList;
// Bereits bestehende Verbindungen verarbeiten
list.connections.forEach(setupConnection);
// Später hinzukommende Verbindungen über die on-Property abfangen
list.onconnectionavailable = (event) => {
setupConnection(event.connection);
};Listener wieder entfernen
const request = new PresentationRequest(['/receiver.html']);
const onAvailable = (event) => {
console.log('Verbindung', event.connection.id, 'verfügbar');
// Nur die erste Verbindung interessiert uns
request.removeEventListener('connectionavailable', onAvailable);
};
request.addEventListener('connectionavailable', onAvailable);
// Alternative Variante mit der on-Property:
// request.onconnectionavailable = onAvailable;
// request.onconnectionavailable = null; // entfernenEvent manuell erzeugen (z. B. für Tests)
// Voraussetzung: Eine vorhandene PresentationConnection, z. B. aus request.start()
const request = new PresentationRequest(['/receiver.html']);
const connection = await request.start();
const evt = new PresentationConnectionAvailableEvent('connectionavailable', {
connection,
});
console.log(evt.type, evt.connection === connection);// Wichtig · Fallstricke
Browser-Kompatibilität: Die Presentation API ist experimentell und wird praktisch nur von Chromium-Browsern auf dem Desktop unterstützt. Firefox und Safari unterstützen sie nicht. Prüfe deshalb vorher, ob die API vorhanden ist, etwa mit if ('PresentationRequest' in window). Die API funktioniert nur in sicheren Kontexten (HTTPS) und kann durch die Permissions Policy presentation gesperrt sein, zum Beispiel in iframes ohne allow="presentation".
- Listener früh registrieren: Setze den Handler für
connectionavailable, bevor dustart()aufrufst odernavigator.presentation.defaultRequestsetzt. Sonst verpasst du Verbindungen, die der Browser selbst startet. - Doppelte Verarbeitung vermeiden:
start()gibt die Verbindung als Promise zurück und löst zusätzlichconnectionavailableaus. Richte die Verbindung deshalb nur an einer Stelle ein, am besten im Event-Handler. - Status der Verbindung: Wenn das Event eintrifft, ist
event.connection.stateoft noch"connecting". Sende Nachrichten erst nach dem Eventconnect, sonst wirftsend()einenInvalidStateError. - Sicherheit: Nachrichten vom Empfänger oder vom Controller gelten als nicht vertrauenswürdige Eingaben. Parse sie mit
JSON.parsein einemtry-Block und schreibe ihren Inhalt nie ungeprüft ininnerHTML(XSS-Gefahr).