Signatur
Beschreibung
Die schreibgeschützte Eigenschaft window.launchQueue gibt ein LaunchQueue-Objekt zurück. Darüber übernimmt eine installierte Progressive Web App (PWA) selbst die Kontrolle darüber, wie sie gestartet wird. Die Eigenschaft gehört zur Launch Handler API und zur File Handling API.
Die einzige Methode ist launchQueue.setConsumer(callback). Der Callback bekommt bei jedem Start ein LaunchParams-Objekt. Darin stehen targetURL (die Adresse, mit der die App gestartet wurde) und files, ein Array aus FileSystemFileHandle-Objekten. files ist gefüllt, wenn der Nutzer die App über „Öffnen mit“ im Betriebssystem gestartet hat.
Richtig nützlich wird das mit dem Manifest-Feld launch_handler. Mit "client_mode": "focus-existing" oder "navigate-existing" öffnet ein neuer Start kein weiteres Fenster. Stattdessen wird ein vorhandenes Fenster fokussiert, und der Consumer empfängt die neuen Startparameter. Das passt zu Einzelfenster-Apps wie Musikplayern, Editoren oder Chat-Clients. Für die Dateiverarbeitung muss das Manifest zusätzlich file_handlers festlegen.
Startereignisse, die vor dem Aufruf von setConsumer() eintreffen, werden in der Warteschlange gepuffert und danach an den Consumer übergeben. Rufen Sie setConsumer() trotzdem möglichst früh beim Laden der Seite auf.
Rückgabewert
LaunchQueue-Objekt des aktuellen Fensters. Es hat die Methode setConsumer(callback: (params: LaunchParams) => void). In Browsern ohne Unterstützung fehlt die Eigenschaft ganz ('launchQueue' in window ergibt false).Beispiele
Unterstützung prüfen und Start-URL auswerten
// Manifest: "launch_handler": { "client_mode": "focus-existing" }
if ('launchQueue' in window) {
window.launchQueue.setConsumer((launchParams) => {
if (!launchParams.targetURL) return;
const url = new URL(launchParams.targetURL);
const track = url.searchParams.get('track');
if (track) {
console.log(`Spiele Titel ${track} im bestehenden Fenster ab`);
}
});
} else {
console.log('Launch Handler API wird nicht unterstützt');
}Über das Betriebssystem geöffnete Dateien einlesen (File Handling)
// Manifest-Ausschnitt:
// "file_handlers": [{ "action": "/editor", "accept": { "text/markdown": [".md"] } }]
const editor = document.querySelector('#editor');
if ('launchQueue' in window) {
window.launchQueue.setConsumer(async ({ files }) => {
if (!files || files.length === 0) return;
for (const handle of files) {
const file = await handle.getFile();
const text = await file.text();
editor.value = text;
document.title = `${file.name} – Editor`;
console.log(`Geladen: ${file.name} (${file.size} Bytes)`);
}
});
}Geöffnete Datei direkt zurückschreiben
let currentHandle = null;
window.launchQueue?.setConsumer(async ({ files }) => {
if (files.length) currentHandle = files[0];
});
const saveFile = async (content) => {
if (!currentHandle) return;
// Schreibrecht wird ggf. beim Nutzer angefragt
const writable = await currentHandle.createWritable();
await writable.write(content);
await writable.close();
console.log('Gespeichert');
};// Wichtig · Fallstricke
- Experimentell und nur in Chromium verfügbar (Chrome/Edge ab Version 102 auf dem Desktop). Firefox und Safari unterstützen die API nicht. Prüfen Sie deshalb immer mit
'launchQueue' in windowoder dem optionalen Verkettungsoperator?., ob sie vorhanden ist. - Die Eigenschaft wirkt nur in einer installierten PWA, die im eigenen Fenster läuft. In einem normalen Browser-Tab erhält der Consumer höchstens die aktuelle URL.
filesbleibt dort leer. - Nur ein sicherer Kontext (HTTPS oder
localhost) ist erlaubt. - Ein erneuter Aufruf von
setConsumer()ersetzt den bisherigen Consumer. Registrieren Sie den Consumer daher nur einmal und zentral. targetURLkann von außen beeinflusst werden, etwa über Links oder Verknüpfungen. Prüfen Sie Abfrageparameter deshalb, bevor Sie sie z. B. in das DOM einfügen (XSS-Gefahr beiinnerHTML).- Für das Schreiben in übergebene Dateien fragt der Browser den Nutzer eventuell um Erlaubnis.