PresentationRequest.start() — Methode · JavaScript-Referenz

Signatur

PresentationRequest.prototype.start()

Beschreibung

start() ist die zentrale Methode der Presentation API auf der steuernden Seite (Controller). Nach dem Aufruf zeigt der Browser einen Auswahldialog mit verfügbaren Präsentationsbildschirmen an, etwa Chromecast-Geräte, Miracast-Empfänger oder angeschlossene zweite Monitore. Wählt der Benutzer einen Bildschirm aus, lädt der Browser dort eine der URLs, die beim Erzeugen des PresentationRequest angegeben wurden, und erfüllt das Promise mit einer PresentationConnection.

Über diese Verbindung tauschen Controller und Empfängerseite Nachrichten mit send() und dem Ereignis message aus. So baut man zum Beispiel Folienpräsentationen, bei denen der Laptop die Folien steuert und der Beamer sie anzeigt, oder Mediaplayer mit Fernbedienungsfunktion.

Die Methode muss durch eine Benutzeraktion ausgelöst werden (transiente Aktivierung, z. B. ein click-Handler). Außerdem darf zur gleichen Zeit nur ein start()-Aufruf pro Dokument offen sein. Wer eine bestehende Präsentation wiederaufnehmen will, nutzt stattdessen PresentationRequest.prototype.reconnect().

Rückgabewert

Typ

Promise<PresentationConnection>

Beschreibung

Ein Promise, das mit der neuen PresentationConnection erfüllt wird, sobald der Benutzer einen Bildschirm ausgewählt hat und die Präsentation gestartet ist. Das Promise wird abgelehnt mit:

NotAllowedError: Es gab keine Benutzeraktion, oder der Aufruf ist durch eine Permissions Policy verboten.
OperationError: Ein anderer start()-Aufruf ist noch offen, oder der Start auf dem Gerät ist fehlgeschlagen.
NotFoundError: Es ist kein passender Bildschirm verfügbar.
AbortError: Der Benutzer hat den Auswahldialog geschlossen.
SecurityError: Der Aufruf kam aus einem Kontext ohne ausreichende Berechtigung, z. B. einem Sandbox-iframe ohne allow-presentation.

Beispiele

Präsentation per Button starten

const request = new PresentationRequest(['receiver.html']);
// Als Standard-Anfrage für das Browser-Menü „Streamen…“ registrieren
navigator.presentation.defaultRequest = request;

document.querySelector('#startBtn').addEventListener('click', async () => {
  try {
    const connection = await request.start();
    console.log('Verbunden, ID:', connection.id);

    connection.addEventListener('connect', () => {
      connection.send(JSON.stringify({ slide: 1 }));
    });
  } catch (err) {
    console.error(`${err.name}: ${err.message}`);
  }
});

Verbunden, ID: 4f3c9a2e-…

Fehlerbehandlung je nach Ursache

const request = new PresentationRequest([
  'https://example.com/slides/receiver.html',
  'cast:ABCDEF12' // Fallback-URL für Cast-Empfänger
]);

const startPresentation = async () => {
  try {
    return await request.start();
  } catch (err) {
    switch (err.name) {
      case 'AbortError':
        console.log('Auswahl vom Benutzer abgebrochen.');
        break;
      case 'NotFoundError':
        console.log('Kein Präsentationsbildschirm gefunden.');
        break;
      case 'NotAllowedError':
        console.log('start() braucht einen Klick des Benutzers.');
        break;
      default:
        console.log('Start fehlgeschlagen:', err.name);
    }
    return null;
  }
};

document.querySelector('#cast').onclick = startPresentation;

Auswahl vom Benutzer abgebrochen.

Verfügbarkeit prüfen, Folien steuern und Verbindung merken

const request = new PresentationRequest(['receiver.html']);
const startBtn = document.querySelector('#startBtn');

// Button nur anzeigen, wenn ein Bildschirm verfügbar ist
request.getAvailability()
  .then((availability) => {
    startBtn.hidden = !availability.value;
    availability.onchange = () => { startBtn.hidden = !availability.value; };
  })
  .catch(() => { startBtn.hidden = false; }); // Überwachung nicht unterstützt

let connection;
let slide = 1;

startBtn.addEventListener('click', async () => {
  connection = await request.start();
  // ID merken, um später mit reconnect() weiterzumachen
  localStorage.setItem('presId', connection.id);
  connection.onmessage = (e) => console.log('Empfänger meldet:', e.data);
  connection.onterminate = () => console.log('Präsentation beendet');
});

document.querySelector('#next').addEventListener('click', () => {
  if (connection?.state === 'connected') {
    connection.send(JSON.stringify({ slide: ++slide }));
  }
});

Empfänger meldet: {"ok":true,"slide":2}

// Wichtig · Fallstricke

Browser-Kompatibilität: Die Presentation API ist experimentell. Sie wird im Wesentlichen nur von Chromium-basierten Browsern unterstützt (Desktop-Chrome mit Cast, eingeschränkt Android). Firefox und Safari unterstützen sie nicht. Prüfen Sie die Unterstützung mit 'PresentationRequest' in window.
Nur sichere Kontexte: Die API steht nur über HTTPS bzw. localhost zur Verfügung.
Benutzeraktion erforderlich: Ohne transiente Aktivierung, z. B. bei einem Aufruf aus setTimeout oder direkt beim Laden der Seite, wird das Promise mit NotAllowedError abgelehnt.
Nur ein Aufruf gleichzeitig: Ein zweiter start()-Aufruf, während der Auswahldialog noch offen ist, schlägt mit OperationError fehl. Deaktivieren Sie den Button deshalb, bis das Promise erfüllt oder abgelehnt ist.
iframes: In eingebetteten Frames braucht es die Permissions Policy presentation und bei Sandbox-iframes zusätzlich allow-presentation.
Verbindungsstatus: Direkt nach dem Erfüllen des Promise kann connection.state noch "connecting" sein. Senden Sie Nachrichten erst nach dem Ereignis connect.
Sicherheit: Nachrichten vom Empfänger gelten als nicht vertrauenswürdig. Parsen Sie sie mit JSON.parse und fügen Sie sie nie ungeprüft per innerHTML ein.

Siehe auch

Navigator.presentation new PaymentRequestEvent() PresentationRequest.reconnect() PresentationRequest.getAvailability() new PresentationRequest()