LaunchQueue — Schnittstelle · JavaScript-Referenz

Signatur

interface LaunchQueue

Beschreibung

Das Interface LaunchQueue gehört zur Launch Handler API und wird über die Eigenschaft window.launchQueue bereitgestellt. Wenn eine installierte Progressive Web App (PWA) gestartet wird, etwa über einen Link, eine Verknüpfung oder eine Dateizuordnung (File Handling API), landet dieser Start in der Warteschlange. Mit setConsumer() meldet die App eine Callback-Funktion an. Diese bekommt für jeden Start ein LaunchParams-Objekt.

Richtig nützlich wird das zusammen mit dem Manifest-Feld launch_handler. Mit "client_mode": "focus-existing" oder "navigate-existing" öffnet sich kein neues Fenster, sondern ein bereits offenes Fenster übernimmt den Start. Die App kann dann per Skript reagieren, zum Beispiel intern zur Ziel-URL routen, ohne neu zu laden, oder die übergebenen Dateien öffnen.

Die Schnittstelle hat genau eine Methode:

setConsumer(callback): meldet den Consumer an. Starts, die vor dem Aufruf eingetroffen sind, werden gepuffert und sofort nachgereicht. Ein erneuter Aufruf ersetzt den bisherigen Consumer.

Das übergebene LaunchParams-Objekt enthält targetURL (die Ziel-URL als String oder null) und files (ein Array aus FileSystemFileHandle-Objekten, wenn die App über eine Dateizuordnung gestartet wurde).

Parameter

Name	Typ	Default	Beschreibung
$callback Pflicht	(launchParams: LaunchParams) => void		Parameter von `setConsumer()`: Funktion, die bei jedem Start der App aufgerufen wird. Sie bekommt ein `LaunchParams`-Objekt mit `targetURL` und `files`.

Rückgabewert

Typ

void

Beschreibung

setConsumer() gibt undefined zurück. Die Start-Daten kommen ausschließlich über den Callback an.

Beispiele

Feature-Erkennung und Consumer registrieren

if ('launchQueue' in window) {
  window.launchQueue.setConsumer((launchParams) => {
    console.log('App gestartet mit:', launchParams.targetURL);
  });
} else {
  console.log('Launch Handler API wird nicht unterstützt');
}

App gestartet mit: https://example.com/app/?view=inbox

Start-URL im bestehenden Fenster verarbeiten (SPA-Routing)

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

const route = (url) => {
  const { pathname, searchParams } = new URL(url);
  history.pushState({}, '', url);
  document.title = `Ansicht: ${searchParams.get('view') ?? pathname}`;
};

window.launchQueue?.setConsumer(({ targetURL }) => {
  if (targetURL) route(targetURL);
});

Über Dateizuordnung geöffnete Dateien einlesen

// manifest.json enthält "file_handlers" für .txt-Dateien
window.launchQueue?.setConsumer(async (launchParams) => {
  if (!launchParams.files.length) return;

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

notizen.txt: 1532 Zeichen

// Wichtig · Fallstricke

Kompatibilität: Die API ist experimentell und läuft nur in Chromium-Browsern (Chrome/Edge ab 110, File Handling ab 102). Firefox und Safari unterstützen sie nicht. Deshalb vorher immer mit 'launchQueue' in window oder optionaler Verkettung (?.) prüfen.
Die API wirkt nur bei installierten PWAs in einem sicheren Kontext (HTTPS). In einem normalen Browser-Tab kommen normalerweise keine Starts an.
Ohne launch_handler im Manifest ist der Standardwert client_mode: "auto". Dann öffnet sich meist ein neues Fenster, und der Consumer wird darin nur einmal aufgerufen.
Den Consumer möglichst früh registrieren, am besten direkt beim Laden des Skripts. Gepufferte Starts werden zwar nachgereicht, aber es gibt immer nur einen Consumer. Ein zweiter Aufruf von setConsumer() ersetzt den ersten.
targetURL kann von außen beeinflusst werden. Die URL deshalb prüfen, bevor man sie ins DOM schreibt oder weiterleitet, sonst drohen XSS oder offene Weiterleitungen.
Die Datei-Handles in files sind vorerst nur lesbar. Zum Schreiben muss man mit requestPermission({ mode: 'readwrite' }) eine Berechtigung anfragen.

Siehe auch

GPUQueue LaunchParams Cache DataCue TouchEvent