Launch 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:包含要由使用方处理的 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:最近一次与 Web 应用窗口中的浏览上下文互动的会转到启动的目标网址。
    • focus-existing:系统会选择最近与 Web 应用窗口中的浏览上下文互动过的上下文来处理启动。将 targetURL 设置为启动网址的新 LaunchParams 对象将在文档的 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 启动处理程序演示中查看 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 提交 bug。请务必提供尽可能详细的信息、重现说明,并在 Components 框中输入 Blink>AppManifest故障非常适合分享快速重现步骤。

显示对该 API 的支持

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

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

实用链接