PresentationRequest — Schnittstelle · JavaScript-Referenz

Signatur

interface PresentationRequest extends EventTarget

Beschreibung

PresentationRequest gehört zur Presentation API. Eine Webseite, der steuernde Browsing-Kontext (controlling browsing context), kann damit eine andere URL auf einem externen Anzeigegerät öffnen, etwa einem Beamer, einem per HDMI angeschlossenen Monitor oder einem Cast-Empfänger. Typische Fälle sind Foliensätze, bei denen der Laptop die Referentenansicht zeigt und der Beamer die Folien, sowie Videoplayer und Spiele mit einem zweiten Bildschirm.

Man übergibt dem Konstruktor eine oder mehrere Präsentations-URLs. Der Browser wählt davon die erste, die ein verfügbares Gerät darstellen kann. Wichtige Mitglieder:

start() zeigt die Geräteauswahl des Browsers und löst mit einer PresentationConnection auf. Die Methode muss durch eine Nutzeraktion ausgelöst werden (transiente Aktivierung).
reconnect(presentationId) verbindet sich erneut mit einer schon laufenden Präsentation, zum Beispiel nach einem Neuladen der Seite.
getAvailability() löst mit einem PresentationAvailability-Objekt auf. Dessen Eigenschaft value und das Ereignis change zeigen an, ob gerade passende Geräte erreichbar sind.
Das Ereignis connectionavailable bzw. die Eigenschaft onconnectionavailable feuert, sobald eine Verbindung aufgebaut ist. Das gilt auch für die Standard-Präsentation über navigator.presentation.defaultRequest.

Über die erhaltene PresentationConnection tauscht die steuernde Seite per send() und message-Ereignis Nachrichten mit der Empfängerseite aus. Die Empfängerseite erreicht ihre Verbindungen über navigator.presentation.receiver.

Parameter

Name	Typ	Default	Beschreibung
$urls Pflicht	string \| string[]		Konstruktor-Argument: eine Präsentations-URL oder eine nach Priorität sortierte Liste davon. Relative URLs werden gegen die Dokument-URL aufgelöst. Ein leeres Array oder eine ungültige URL löst einen `SyntaxError` aus.
$presentationId Pflicht	string		Nur bei `reconnect()`: die `id` einer früheren `PresentationConnection`.

Rückgabewert

Typ

PresentationRequest

Beschreibung

new PresentationRequest(urls) liefert eine neue Instanz. start() und reconnect() geben Promise<PresentationConnection> zurück, getAvailability() gibt Promise<PresentationAvailability> zurück.

Beispiele

Präsentation per Button-Klick starten

const request = new PresentationRequest(['slides/receiver.html']);

document.querySelector('#present').addEventListener('click', async () => {
  try {
    const connection = await request.start();
    // ID merken, um später wieder verbinden zu können
    localStorage.setItem('presId', connection.id);
    connection.addEventListener('connect', () => {
      connection.send(JSON.stringify({ slide: 1 }));
    });
    connection.addEventListener('message', (e) => console.log('Empfänger:', e.data));
  } catch (err) {
    // NotAllowedError: Nutzer hat den Dialog abgebrochen
    // NotFoundError: kein Gerät verfügbar
    console.warn(err.name, err.message);
  }
});

Empfänger: {"ready":true}

Button nur bei verfügbaren Geräten anzeigen

const request = new PresentationRequest('player/receiver.html');
const button = document.querySelector('#cast');

try {
  const availability = await request.getAvailability();
  const update = () => { button.hidden = !availability.value; };
  update();
  availability.addEventListener('change', update);
} catch {
  // Überwachung nicht unterstützt: Button trotzdem anbieten
  button.hidden = false;
}

Nach dem Neuladen wieder verbinden

const request = new PresentationRequest(['slides/receiver.html']);
const savedId = localStorage.getItem('presId');

if (savedId) {
  try {
    const connection = await request.reconnect(savedId);
    console.log('Wieder verbunden:', connection.state);
  } catch (err) {
    console.log('Keine laufende Präsentation:', err.name);
    localStorage.removeItem('presId');
  }
}

Wieder verbunden: connected

Standard-Präsentation mit onconnectionavailable

if ('PresentationRequest' in window) {
  const request = new PresentationRequest('receiver.html');
  // Wird genutzt, wenn der Nutzer über das Browsermenü („Streamen…“) präsentiert
  navigator.presentation.defaultRequest = request;
  request.onconnectionavailable = ({ connection }) => {
    console.log('Verbunden mit ID', connection.id);
  };
}

Verbunden mit ID 3f2a…

// Wichtig · Fallstricke

Browser-Unterstützung: Die API ist experimentell und praktisch nur in Chromium-Browsern (Chrome, Edge) auf dem Desktop umgesetzt, dort vor allem für Cast-Geräte. Firefox und Safari unterstützen sie nicht. Vor der Nutzung sollte man das mit 'PresentationRequest' in window prüfen.
Sicherer Kontext: Die API ist nur unter HTTPS bzw. localhost verfügbar. Aus einem sicheren Kontext heraus lassen sich keine Präsentations-URLs mit http: öffnen, das führt zu einem SecurityError.
Nutzeraktion nötig: start() ohne transiente Aktivierung (z. B. direkt beim Laden der Seite) wird mit InvalidAccessError bzw. NotAllowedError abgewiesen. Es darf außerdem immer nur ein start()-Aufruf gleichzeitig offen sein, sonst folgt ein OperationError.
Kein Gerät gefunden: getAvailability() kann mit NotSupportedError abgelehnt werden, wenn die Plattform keine dauerhafte Geräteüberwachung erlaubt. Das heißt nicht, dass start() scheitert.
Nachrichten: Daten, die über PresentationConnection.send() ankommen, sollte man auf der Empfängerseite wie jede externe Eingabe prüfen und nicht ungefiltert per innerHTML einfügen, sonst droht XSS.
In Iframes wird die Berechtigungsrichtlinie presentation benötigt, z. B. <iframe allow="presentation">.

Siehe auch

Presentation PresentationReceiver PaymentRequest PresentationConnection OrientationSensor