Launch Handler API

控制应用的启动方式。

Thomas Steiner

借助 Launch Handler API，您可以控制应用的启动方式，例如应用是使用现有窗口还是新窗口，以及所选窗口是否会导航到启动网址。与 File Handling 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：在 Web 应用窗口中创建新的浏览上下文，以加载启动操作的目标网址。
    • navigate-existing：在网页应用窗口中最近与浏览上下文互动的内容会导航到启动操作的目标网址。
    • focus-existing：系统会选择最近与 Web 应用窗口中的浏览上下文互动过的上下文来处理启动。系统会将一个新的 LaunchParams 对象的 targetURL 设置为启动网址，并将其加入文档的 window.launchQueue 队列。
    • 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 启动处理程序演示中查看启动处理程序 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 实现中的 bug？或者实现方式是否与规范不同？ 请访问 new.crbug.com 提交 bug。请务必提供尽可能详细的信息、重现说明，并在 Components 框中输入 Blink>AppManifest。故障非常适合分享快速重现步骤。

显示对该 API 的支持

您打算使用 Launch Handler API 吗？您的公开支持有助于 Chromium 团队确定功能的优先级，并向其他浏览器供应商表明支持这些功能的重要性。

使用 #LaunchHandler 标签向 @ChromiumDev 发送推文，告诉我们您在哪里以及如何使用该工具。

实用链接