Handler API starten

Festlegen, wie Ihre App gestartet wird

Thomas Steiner

Mit der Launch Handler API können Sie steuern, wie Ihre App gestartet wird, z. B. ob sie ein vorhandenes oder ein neues Fenster verwendet und ob das ausgewählte Fenster zur Start-URL navigiert wird. Wie bei der File Handling API wird auch hier ein LaunchParams-Objekt in die window.launchQueue der gestarteten Seite eingereiht.

Aktueller Status

Schritt Status
1. Erklärung erstellen Abschließen
2. Ersten Entwurf der Spezifikation erstellen Abschließen
3. Feedback einholen und Design iterieren Abgeschlossen
4. Ursprungstest Abgeschlossen
5. Launch Abschließen

Launch Handler API verwenden

Unterstützte Browser

Schnittstellen

Die Launch Handler API definiert zwei neue Schnittstellen.

LaunchParams : Ein Objekt, das die vom Nutzer zu bearbeitende targetURL enthält. LaunchQueue : Warteschlangen werden gestartet, bis sie vom angegebenen Consumer verarbeitet werden.

Das launch_handler-Manifestmitglied

Wenn Sie das Startverhalten Ihrer App deklarativ festlegen möchten, fügen Sie Ihrem Manifest das Manifestelement launch_handler hinzu. Es hat ein untergeordnetes Feld namens client_mode. Damit können Sie steuern, ob ein neuer oder ein vorhandener Client gestartet werden soll und ob dieser Client navigiert werden soll. Das folgende Beispiel zeigt eine Datei mit Beispielwerten, die alle Starts immer an einen neuen Client weiterleiten würden.

{
  "launch_handler": {
    "client_mode": "navigate-new"
  }
}

Wenn nicht angegeben, wird für launch_handler standardmäßig {"client_mode": "auto"} verwendet. Zulässige Werte für die Unterfelder:

  • client_mode:
    • navigate-new: In einem Web-App-Fenster wird ein neuer Browserkontext erstellt, um die Ziel-URL des Starts zu laden.
    • navigate-existing: Der zuletzt verwendete Browserkontext in einem Web-App-Fenster wird zur Ziel-URL des Starts navigiert.
    • focus-existing: Der zuletzt verwendete Browserkontext in einem Web-App-Fenster wird für den Start ausgewählt. Ein neues LaunchParams-Objekt, dessen targetURL auf die Start-URL festgelegt ist, wird in die window.launchQueue des Dokuments eingereiht.
    • auto: Das Verhalten hängt vom User-Agent ab, der entscheidet, was für die Plattform am besten geeignet ist. Auf Mobilgeräten wird beispielsweise nur ein Client unterstützt und existing-client verwendet, während auf Desktopgeräten mehrere Fenster unterstützt werden und navigate-new verwendet wird, um Datenverlust zu vermeiden.

Für die client_mode-Eigenschaft kann auch eine Liste (ein Array) von Werten angegeben werden. In diesem Fall wird der erste gültige Wert verwendet. So können der Spezifikation neue Werte hinzugefügt werden, ohne die Abwärtskompatibilität mit bestehenden Implementierungen zu beeinträchtigen.

Wenn beispielsweise der hypothetische Wert "focus-matching-url" hinzugefügt würde, würden Websites "client_mode": ["focus-matching-url", "navigate-existing"] angeben, um das Verhalten älterer Browser, die "focus-matching-url" nicht unterstützen, weiterhin zu steuern.

window.launchQueue verwenden

Im folgenden Code extrahiert die Funktion extractSongID() einen songID aus der beim Start übergebenen URL. Damit kann ein Song in einer Musikplayer-PWA wiedergegeben werden.

if ('launchQueue' in window) {
  launchQueue.setConsumer((launchParams) => {
    if (launchParams.targetURL) {
      const songID = extractSongId(launchParams.targetURL);
      if (songID) {
        playSong(songID);
      }
    }
  });
}

Demo

Eine Demo der Launch Handler API in Aktion finden Sie in der PWA Launch Handler Demo. Sehen Sie sich den Quellcode der Anwendung an, um zu sehen, wie die Launch Handler API verwendet wird.

  1. Installiere die Musicr 2.0 App.
  2. Senden Sie sich selbst einen Link im Format https://mdn.github.io/dom-examples/launch-handler/?track=https://example.com/music.mp3 in einer Chat-Anwendung. Du kannst https://example.com/music.mp3 für jede URL anpassen, die auf eine Audiodatei verweist, z. B. https://mdn.github.io/dom-examples/launch-handler/?track=https://huggingface.co/spaces/VIDraft/PHI4-Multimodal/resolve/main/examples/harvard.wav.
  3. Klicken Sie in Ihrer Chat-App auf den Link. Musicr 2.0 wird geöffnet und der Titel wird abgespielt.
  4. Klicken Sie noch einmal auf den Link in Ihrer Chat-App. Es wird keine zweite Instanz von Musicr 2.0 geöffnet.

Feedback

Das Chromium-Team möchte mehr über Ihre Erfahrungen mit der Launch Handler API erfahren.

Informationen zum API-Design

Gibt es etwas an der API, das nicht wie erwartet funktioniert? Oder fehlen Methoden oder Eigenschaften, die Sie für die Umsetzung Ihrer Idee benötigen? Haben Sie Fragen oder Anmerkungen zum Sicherheitsmodell? Melden Sie ein Spezifikationsproblem im entsprechenden GitHub-Repository oder fügen Sie Ihre Gedanken zu einem bestehenden Problem hinzu.

Problem mit der Implementierung melden

Haben Sie einen Fehler in der Chromium-Implementierung gefunden? Oder weicht die Implementierung von der Spezifikation ab? Melden Sie einen Fehler unter new.crbug.com. Geben Sie dabei so viele Details wie möglich und eine Anleitung zur Reproduktion an und geben Sie Blink>AppManifest in das Feld Components (Komponenten) ein.

API-Support zeigen

Planen Sie, die Launch Handler API zu verwenden? Ihr öffentlicher Support hilft dem Chromium-Team, Funktionen zu priorisieren, und zeigt anderen Browseranbietern, wie wichtig es ist, sie zu unterstützen.

Senden Sie einen Tweet an @ChromiumDev mit dem Hashtag #LaunchHandler und teilen Sie uns mit, wo und wie Sie die Funktion verwenden.

Nützliche Links