LaunchParams — Schnittstelle · JavaScript-Referenz

Signatur

interface LaunchParams

Beschreibung

Das Interface LaunchParams gehört zur Launch Handler API. Damit kann eine installierte Progressive Web App (PWA) selbst steuern, was bei einem Start passiert: z. B. ob ein bereits geöffnetes App-Fenster wiederverwendet wird, statt ein neues Fenster zu öffnen, und wie die gewünschte Ziel-URL in diesem Fenster verarbeitet wird.

Instanzen von LaunchParams erzeugt man nicht selbst. Der Browser legt sie bei jedem Start an und stellt sie in die window.launchQueue. Mit launchQueue.setConsumer(callback) meldet die App einen Callback an, der für jeden Start (auch für Starts vor der Anmeldung, die in der Warteschlange gepuffert wurden) ein LaunchParams-Objekt bekommt.

Das Objekt hat zwei schreibgeschützte Eigenschaften:

targetURL: die URL, mit der die App gestartet wurde (z. B. über einen Link, eine Verknüpfung oder das Startmenü), oder null.
files: ein Array aus FileSystemFileHandle-Objekten, wenn die App über die File Handling API (Manifest-Eintrag file_handlers) mit Dateien geöffnet wurde. Sonst ist das Array leer.

Wie gestartet wird, legt der Manifest-Eintrag launch_handler.client_mode fest ("auto", "navigate-new", "navigate-existing", "focus-existing"). Vor allem bei "focus-existing" ist LaunchParams wichtig. Der Browser navigiert dann nicht selbst, und die App muss targetURL selbst auswerten, z. B. über ihren clientseitigen Router.

Parameter

Name	Typ	Default	Beschreibung
$targetURL	string \| null	null	Schreibgeschützte Eigenschaft: die Ziel-URL des Starts. Ist `null`, wenn keine URL übergeben wurde, z. B. bei einem reinen Dateistart.
$files	ReadonlyArray<FileSystemHandle>	[]	Schreibgeschützte Eigenschaft: die Datei-Handles, die beim Start über die File Handling API übergeben wurden. Den Inhalt liest man mit `handle.getFile()`.

Rückgabewert

Typ

LaunchParams

Beschreibung

Man erzeugt die Objekte nicht selbst. Man bekommt sie als einziges Argument im Callback von window.launchQueue.setConsumer().

Beispiele

Manifest: vorhandenes Fenster fokussieren

// manifest.webmanifest (JSON, hier als JS-Objekt gezeigt)
const manifest = {
  name: "Notizen",
  start_url: "/",
  display: "standalone",
  launch_handler: {
    client_mode: "focus-existing"
  }
};
console.log(JSON.stringify(manifest.launch_handler));

{"client_mode":"focus-existing"}

Ziel-URL im eigenen Router verarbeiten

// Clientseitiges Routing bei "focus-existing"
const route = (url) => {
  const { pathname, searchParams } = new URL(url);
  console.log(`Öffne Ansicht ${pathname}`, Object.fromEntries(searchParams));
  history.pushState({}, "", url);
};

if ("launchQueue" in window) {
  window.launchQueue.setConsumer((launchParams) => {
    if (launchParams.targetURL) {
      route(launchParams.targetURL);
    }
  });
} else {
  console.log("Launch Handler API wird nicht unterstützt");
}

Öffne Ansicht /notiz {id: "42"}

Mit Dateien gestartet (File Handling API)

// Voraussetzung: Manifest enthält "file_handlers" für z. B. .txt
if ("launchQueue" in window) {
  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`);
    }
  });
}

einkauf.txt: 128 Zeichen

Starts zählen und Fenster wiederverwenden

let launches = 0;

window.launchQueue?.setConsumer(({ targetURL, files }) => {
  launches += 1;
  console.log(`Start #${launches}`, targetURL ?? "(keine URL)", `${files.length} Datei(en)`);
  document.title = `Notizen – Start ${launches}`;
});

Start #1 https://example.com/ 0 Datei(en)

// Wichtig · Fallstricke

Experimentell und nur in Chromium: Die API gibt es in Chrome und Edge (Desktop, ab Version 110). Firefox und Safari unterstützen sie nicht. Prüfen Sie die Verfügbarkeit immer vorher mit "launchQueue" in window.
Die API wirkt nur in einer installierten PWA, die in einem eigenen App-Fenster läuft. In einem normalen Browser-Tab kommen in der Regel keine Start-Parameter an.
Pro Dokument sollten Sie setConsumer() nur einmal aufrufen. Ein neuer Aufruf ersetzt den bisherigen Callback. Starts, die vor der Anmeldung passiert sind, werden gepuffert und danach zugestellt.
Bei client_mode: "focus-existing" navigiert der Browser nicht. Wenn Sie targetURL nicht auswerten, landet der Nutzer nicht auf der gewünschten Seite.
files enthält nur dann Einträge, wenn im Manifest passende file_handlers stehen. Ein erneuter Schreibzugriff auf die Dateien kann eine Rückfrage an den Nutzer auslösen.
Sicherheit: Behandeln Sie targetURL und Dateiinhalte als nicht vertrauenswürdige Eingaben. Parameter aus der URL dürfen nicht ungeprüft in innerHTML landen (Gefahr von XSS).

Siehe auch

Pbkdf2Params AesCbcParams AesCtrParams AesGcmParams AudioParam