使用声明式链接捕获功能,选择报告范围内的链接如何打开 PWA

什么是声明式链接捕获?

点击网页上的链接有时会带来惊喜。例如,在移动设备上点击指向 YouTube 的网页链接会打开 YouTube iOS 或 Android 应用(如果已安装)。但如果您在桌面计算机上安装 YouTube PWA 并点击某个链接,该链接会在浏览器标签页中打开。

但情况会变得更加复杂。如果链接不是显示在网站上,而是显示在您在 Google 的某款聊天应用中收到的聊天消息中,该怎么办?在具有单独应用窗口概念的桌面操作系统上,如果应用已打开,是否应为每次点击链接都创建一个新窗口或标签页?实际上,捕获链接和导航的方式有很多,包括但不限于以下方式:

声明式链接捕获是一项提案,旨在为 Web 应用清单添加一个名为 "capture_links" 的属性,让开发者能够以声明方式确定当浏览器从导航范围之外的上下文导航到应用导航范围内的网址时应发生什么情况。如果用户已在导航范围内(例如,用户打开的浏览器标签页在范围内,并点击了内部链接),则此提案不适用。

某些特殊情况(例如中键点击链接或右键点击链接,然后选择“在新标签页中打开”)通常不会触发链接捕获行为。链接是 target=_self 还是 target=_blank 并不重要,因此,即使在浏览器窗口(或其他 PWA 的窗口)中点击的链接通常会导致在同一标签页中进行导航,也会在 PWA 中打开。

建议的应用场景

以下是一些可能使用此 API 的网站示例:

  • 希望在用户点击指向它们的链接时打开窗口(而非浏览器标签页)的 PWA。在桌面环境中,同时打开多个应用窗口通常很有意义。
  • 单窗口 PWA,开发者希望在任何时候只打开一个应用实例,并且新的导航会聚焦于现有实例。子使用情形包括:
    • 适合只运行一个实例的应用(例如音乐播放器、游戏)。
    • 在单个实例中包含多文档管理的应用(例如,通过 HTML 实现的标签页栏)。

通过 about://flags 启用

如需在本地试用声明式链接捕获功能,而无需源试用令牌,请在 about://flags 中启用 #enable-desktop-pwas-link-capturing 标志。

如何使用声明式链接捕获?

开发者可以利用额外的 Web 应用清单字段 "capture_links" 以声明方式确定应如何捕获链接。它接受字符串或字符串数组作为值。如果提供的是字符串数组,用户代理会选择列表中第一个受支持的项,默认值为 "none"。支持使用以下值:

  • "none"(默认):不捕获链接;点击导致进入此 PWA 范围的链接会正常导航,而不会打开 PWA 窗口。
  • "new-client":每次点击链接都会在该网址打开一个新的 PWA 窗口。
  • "existing-client-navigate":点击的链接会在现有的 PWA 窗口(如果有)中打开,否则会在新窗口中打开。如果存在多个 PWA 窗口,浏览器可能会任意选择一个。如果没有窗口当前处于打开状态,此行为与 "new-client" 类似。🚨 请务必小心!此选项可能会导致数据丢失,因为用户可以随意离开网页。网站应注意,选择此选项即表示选择启用此类行为。此选项最适合不将用户数据保存在内存中的“只读”网站,例如音乐播放器。如果用户要离开的网页具有 beforeunload 事件,那么用户会在导航完成之前看到提示。

演示

声明式链接捕获的演示实际上包含两个相互交互的演示:

  1. 网站 1
  2. 网站 2

下面的屏幕录制视频展示了这两者如何互动。它们显示了两种不同的行为,即 "new-client""existing-client-navigate"。请务必测试处于不同状态的应用(在标签页中运行或作为已安装的 PWA 运行),以查看行为差异。

安全与权限

Chromium 团队根据控制对强大的 Web 平台功能的访问中定义的核心原则(包括用户控制、透明度和人体工程学),设计并实现了声明式链接捕获。此 API 为网站提供了新的额外控制选项。首先,能够自动在窗口中打开已安装的应用。此方法使用现有界面,但可让网站自动触发该界面。其次,能够将现有窗口聚焦到其自己的网域,并触发包含所点击网址的事件。此属性旨在允许网站将现有窗口导航到新网页,从而替换默认的 HTML 导航流程。

迁移到 Launch Handler API

Declarative Link Capturing API 源试用已于 2022 年 3 月 30 日针对 Chromium 97 及更低版本过期。在 Chromium 98 及更高版本中,它将被一组新功能和 API 取代,其中包括用户启用的链接捕获和 Launch Handler API

在 Chromium 98 中,自动链接捕获现在是一种用户选择启用的行为,而不是在安装时授予 Web 应用的权限。如需启用链接捕获,用户需要使用打开方式从浏览器启动已安装的应用,然后选择记住我的选择

已安装应用的“打开方式”设置示例,其中“记住我的选择”选项处于启用状态。

或者,用户可以在应用管理设置页面中针对特定 Web 应用开启或关闭链接捕获功能。

已安装应用的设置页面示例。

链接捕获目前仅是 ChromeOS 功能;我们正在努力实现对 Windows、macOS 和 Linux 的支持。

启动处理程序 API

对传入导航的控制已迁移到 Launch Handler API,该 API 允许 Web 应用决定在各种情况下(例如链接捕获、共享目标或文件处理等)如何启动 Web 应用。如需从 Declarative Link Capturing API 迁移到 Launch Handler API,请执行以下操作:

  1. 注册您的网站以参加 Launch Handler 源试用,并将源试用密钥放置到您的 Web 应用中。
  2. 向网站的清单添加 "launch_handler" 条目。

    • 如需使用 "capture_links": "new-client",请添加:"launch_handler": { "route_to": "new-client" }
    • 如需使用 "capture_links": "existing-client-navigate",请添加: "launch_handler": { "route_to": "existing-client-navigate" }
    • 如需使用 "capture_links": "existing-client-event"(从未在声明式链接捕获源试用中实现),请添加:"launch_handler": { "route_to": "existing-client-retain" }。 选择此选项后,当捕获到链接导航时,应用范围内的网页将不再自动导航。您必须通过调用 window.launchQueue.setConsumer() 在 JavaScript 中处理 LaunchParams 以启用导航。

capture_links 字段和声明式链接捕获源试用注册的有效期至 2022 年 3 月 30 日。这样可确保使用 Chromium 97 及更低版本的用户仍能通过捕获的链接启动 Web 应用。

如需了解详情,请参阅控制应用的启动方式

反馈

Chromium 团队希望了解您在使用声明式链接捕获功能时的体验。

介绍 API 设计

API 是否存在未按预期运行的情况?或者,是否有缺少的方法或属性需要您来实现自己的想法?对安全模型有疑问或意见?在相应的 GitHub 代码库中提交规范问题,或在现有问题中添加您的想法。

报告实现方面的问题

您是否发现了 Chromium 的实现存在 bug?或者实现是否与规范不同? 请前往 new.crbug.com 提交 bug。请务必尽可能详细地说明问题,提供简单的重现说明,并在组件框中输入 UI>Browser>WebAppInstalls

显示对 API 的支持

您是否打算使用声明式链接捕获?您的公开支持有助于 Chromium 团队确定功能优先级,并向其他浏览器供应商展示支持这些功能的重要性。

使用 #ChromiumDev 标签向 @ChromiumDev 发送推文,告诉我们您在何处以及如何使用它。#DeclarativeLinkCapturing

实用链接

致谢

声明式链接捕获由 Matt Giuca 指定,并参考了 Alan Cutter 和 Dominick Ng 的意见。该 API 由 Alan Cutter 实现。本文由 Joe Medley、Matt Giuca、Alan Cutter 和 Shunya Shishido 审核。主打图片由 Zulmaury SaavedraUnsplash 上提供。