啟動 Handler API

控管應用程式的啟動方式。

Thomas Steiner

您可以使用 Launch Handler API 控管應用程式的啟動方式，例如使用現有或新視窗，以及是否要導覽至啟動網址。與 File Handing API 一樣，這也會在啟動頁面的 window.launchQueue 中將 LaunchParams 物件排入佇列。

目前狀態

步驟 狀態
1. 建立說明 完成
2. 建立規格初稿 完成
3. 收集意見回饋並重複設計 完成
4. 來源試用。 完成
5. 發布 完成

使用 Launch Handler API

瀏覽器支援

瀏覽器支援

  • Chrome：110。
  • Edge：110，
  • Firefox：不支援。
  • Safari：不支援。

資料來源

介面

Launch Handler API 定義了兩個新介面。

LaunchParams：包含由消費者處理的 targetURL 物件。LaunchQueue：啟動佇列，直到指定的用戶處理為止。

launch_handler 資訊清單成員

如要以宣告方式指定應用程式的啟動行為，請在資訊清單中新增 launch_handler 資訊清單成員。其中包含一個名為 client_mode 的子欄位。它可讓您控制是否應啟動現有用戶端或現有用戶端，以及是否應前往該用戶端。以下範例顯示含有示範值的檔案，該檔案會一律將所有啟動作業導向新用戶端。

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

如果未指定，launch_handler 預設為 {"client_mode": "auto"}。子欄位的有效值如下：

  • client_mode：
    • navigate-new：在網頁應用程式視窗中建立新的瀏覽內容，以載入啟動目標網址。
    • navigate-existing：在網頁應用程式視窗中，最近與瀏覽內容互動的內容會導向啟動目標網址。
    • focus-existing：系統會選擇最近與網頁應用程式視窗中的瀏覽內容互動的內容，用於處理啟動作業。新的 LaunchParams 物件會在文件的 window.launchQueue 中排入佇列，其 targetURL 會設為啟動網址。
    • auto：行為取決於使用者代理程式，決定最適合平台的行為。舉例來說，行動裝置只支援單一用戶端，因此會使用 existing-client，而電腦裝置支援多個視窗，因此會使用 navigate-new 避免資料遺失。

client_mode 屬性也接受值清單 (陣列)，並使用第一個有效值。這麼做是為了讓新的值能夠加入規格，而不會破壞與現有實作的回溯相容性。

舉例來說，如果新增假設值 "focus-matching-url"，網站會指定 "client_mode": ["focus-matching-url", "navigate-existing"]，繼續控制不支援 "focus-matching-url" 的舊版瀏覽器行為。

使用 window.launchQueue

在以下程式碼中，extractSongID() 函式會從啟動時傳遞的網址中擷取 songID。用於在音樂播放器 PWA 中播放歌曲。

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

示範

如要查看 Launch Handler API 的實際操作示範，請參閱 PWA 啟動處理常式示範。請務必查看應用程式的原始碼，瞭解應用程式如何使用 Launch Handler API。

  1. 安裝 Musicr 2.0 應用程式。
  2. 透過即時通訊應用程式傳送 https://launch-handler.glitch.me?track=https://example.com/music.mp3 格式的連結給自己。(您可以針對指向音訊檔案的任何網址自訂 https://example.com/music.mp3，例如 https://launch-handler.glitch.me?track=https://cdn.glitch.me/3e952c9c-4d6d-4de4-9873-23cf976b422e%2Ffile_example_MP3_700KB.mp3?v=1638795977190)。
  3. 點選聊天室應用程式中的連結，看看 Musicr 2.0 如何開啟並播放曲目。
  4. 再次點選即時通訊應用程式中的連結，您就不會收到第二個 Musicr 2.0 例項。

意見回饋

Chromium 團隊想瞭解你的 Launch Handler API 使用體驗。

請說明 API 設計

您覺得這個 API 有任何不如預期的運作方式嗎？還是你還需要實現想法或屬性呢？您對安全性模型有任何問題或意見嗎？在對應的 GitHub 存放區中提出規格問題，或在現有問題中加入您的想法。

回報實作問題

您發現 Chromium 實作錯誤嗎？或者實作方式與規格不同？前往 new.crbug.com 回報錯誤。請務必盡量提供詳細資料、重現問題的操作說明，並在「Components」(元件) 方塊中輸入 Blink>AppManifest。Glitch 非常適合用於分享快速重現問題的資訊。

顯示對 API 的支援

您打算使用 Launch Handler API 嗎？您公開表示的支持，有助於 Chromium 團隊將功能列為優先，並向其他瀏覽器供應商顯示，支援這些功能的重要性。

使用主題標記 #LaunchHandler 發送推文給 @ChromiumDev，告訴我們你在何處使用這項功能，以及使用方式。

實用連結