啟動 Handler API

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

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:這個物件含有要由取用端處理的 targetURLLaunchQueue:佇列會啟動,直到指定的消費者處理為止。

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);
      }
    }
  });
}

示範

您可以在 PWA 啟動處理常式示範中,查看 Launch Handler API 的實際運作情形。請務必查看應用程式的原始碼,瞭解應用程式如何使用 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>AppManifestGlitch 非常適合用於分享快速重現問題的資訊。

顯示對 API 的支援

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

使用主題標記將推文傳送至 @ChromiumDev #LaunchHandler和 請告訴我們您使用應用程式的位置和方式。

實用連結