LaunchQueue.setConsumer() — Methode · JavaScript-Referenz

Signatur

LaunchQueue.prototype.setConsumer(consumer)

Beschreibung

Mit setConsumer() legst du fest, welche Funktion Startvorgänge (Launches) einer installierten progressiven Web-App verarbeitet. Die Methode gehört zur Launch Handler API. Aufgerufen wird sie über das globale Objekt window.launchQueue. Bei jedem Start der App, zum Beispiel über einen Link, das Startmenü oder einen Dateityp, der im Manifest unter file_handlers registriert ist, ruft der Browser deinen Callback mit einem LaunchParams-Objekt auf.

Nützlich ist das vor allem mit dem Manifest-Feld launch_handler und dessen Eigenschaft client_mode. Steht dort "navigate-existing" oder "focus-existing", öffnet der Browser kein neues Fenster. Stattdessen wird ein bereits offenes Fenster wiederverwendet, und die Anwendung entscheidet selbst, wie sie auf den Start reagiert, etwa indem sie in ein bestimmtes Dokument springt, statt die Seite neu zu laden.

Startvorgänge, die vor dem Aufruf von setConsumer() passieren, puffert der Browser in einer Warteschlange. Sobald ein Consumer registriert ist, stellt er sie diesem zu. Ruft man die Methode erneut auf, ersetzt der neue Callback den alten. Es ist also immer nur ein Consumer aktiv.

Parameter

Name	Typ	Default	Beschreibung
$consumer Pflicht	(launchParams: LaunchParams) => any		Callback, der für jeden Startvorgang aufgerufen wird. Er erhält ein `LaunchParams`-Objekt mit `targetURL` (`string \| null`): die URL, mit der gestartet wurde, und `files` (`FileSystemHandle[]`): per File-Handling geöffnete Dateien, sonst ein leeres Array.

Beispiele

Startvorgänge mit Feature-Erkennung verarbeiten

// Nur ausführen, wenn der Browser die Launch Handler API kennt
if ('launchQueue' in window) {
  window.launchQueue.setConsumer((launchParams) => {
    console.log('Gestartet mit:', launchParams.targetURL);
    console.log('Anzahl Dateien:', launchParams.files.length);
  });
} else {
  console.log('Launch Handler API nicht verfügbar');
}

Gestartet mit: https://example.com/app/?doc=42 Anzahl Dateien: 0

Ziel-URL im bereits offenen Fenster auswerten (client_mode: focus-existing)

// manifest.webmanifest:
// "launch_handler": { "client_mode": "focus-existing" }

const openDocument = (id) => {
  document.querySelector('#title').textContent = `Dokument ${id}`;
  console.log(`Öffne Dokument ${id}`);
};

if ('launchQueue' in window) {
  launchQueue.setConsumer(({ targetURL }) => {
    if (!targetURL) return;
    const url = new URL(targetURL);
    const docId = url.searchParams.get('doc');
    if (docId) openDocument(docId);
  });
}

Öffne Dokument 42

Dateien öffnen, die über file_handlers übergeben wurden

// manifest.webmanifest:
// "file_handlers": [{ "action": "/editor", "accept": { "text/markdown": [".md"] } }]

if ('launchQueue' in window) {
  launchQueue.setConsumer(async (launchParams) => {
    if (!launchParams.files.length) return;

    for (const handle of launchParams.files) {
      if (handle.kind !== 'file') continue;
      const file = await handle.getFile();
      const text = await file.text();
      console.log(`${file.name}: ${text.length} Zeichen`);
    }
  });
}

notizen.md: 1284 Zeichen

// Wichtig · Fallstricke

Kompatibilität: Die API ist experimentell. Sie läuft nur in Chromium-Browsern (Chrome und Edge ab Version 102) und nur in installierten PWAs, auf Desktop-Systemen am zuverlässigsten. Firefox und Safari unterstützen sie nicht. Prüfe deshalb immer vorher mit 'launchQueue' in window.
Im normalen Browser-Tab passiert meist nichts: Der Callback wird nur beim Start der installierten App aufgerufen. Einzige Ausnahme ist ein einmaliger Aufruf beim Laden der Seite, dessen targetURL der aktuellen URL entspricht.
Rufe setConsumer() möglichst früh beim Laden der Seite auf. Gepufferte Startvorgänge gehen zwar nicht verloren, aber bis zur Registrierung sieht der Nutzer keine Reaktion.
Jeder weitere Aufruf ersetzt den vorherigen Consumer. Registriere den Consumer deshalb zentral an einer Stelle und nicht in mehreren Modulen.
targetURL kann null sein. Prüfe den Wert, bevor du ihn an new URL() übergibst.
Sicherheit: Behandle Ziel-URL und Dateiinhalte als Eingaben, denen du nicht vertrauen kannst. Setze sie nicht ungeprüft per innerHTML ins DOM (XSS-Gefahr).
Wird client_mode auf "focus-existing" gesetzt, navigiert der Browser nicht. Ohne Consumer bekommt die App den Start dann gar nicht mit.

Siehe auch

Sanitizer.setComments() GPUQueue.submit() GPUQueue.writeBuffer() Range.setEndAfter() AudioContext.resume()