Web 应用范围扩展

从 Chrome 122 开始，您可以订阅 scope_extensions 应用清单成员的源试用，该成员允许控制多个子网域和顶级网域的网站显示为单个 Web 应用。本文档介绍了 Chrome 团队引入此功能的原因，以及您可能需要使用此功能的情况。

Demián Renzulli

Thomas Steiner

概览

某些 Web 应用具有多个来源，例如，example.com 作为主应用，然后 space_1.example.com、…、space_n.example.com（有时与 special-example.com 结合使用）作为子体验，所有这些都位于主应用的范围内。这种类型的网站架构在渐进式 Web 应用方面具有重要意义。限制包括无法跨源共享服务工作线程、任何类型的设备、本地存储空间和权限。此外，在独立 PWA 中进行跨源导航时，系统会显示一个窗口界面（“超出范围”栏），表明用户已离开 PWA 体验。您可以参阅多源网站中的渐进式 Web 应用和在同一网域上构建多个渐进式 Web 应用这两篇文章，了解如何解决其中一些问题。

借助 Scope Extensions API，Web 应用可以克服同源政策对此类网站架构施加的一些限制。它允许 Web 应用将其范围扩展到其他来源，从而在 Web 应用的主来源与关联来源之间达成一致的情况下，帮助实现统一的体验。

目标

Scope Extensions API 的主要目标是允许控制多个子网域和顶级网域的网站在 Web 应用界面和链接捕获方面表现为一个连续的 Web 应用。例如，让跨越 example.com.co.uk 和 support.example.com 的网站 example.com 尽可能像单个 Web 应用一样运行。

显示主 PWA 和关联的子体验的示意图。

范围扩展功能可让多源 PWA 在 Web 应用界面方面表现得像一个连续的 Web 应用。

在实践中，这会转化为两个更具体的目标：

跨源导航：允许用户在关联的源之间导航，而不会通过调用窗口界面来告知用户他们正在离开 PWA，从而避免干扰用户体验。
跨源链接捕获：允许 Web 应用捕获用户导航到其关联网站的操作。

跨源范围内导航

默认情况下，当用户在独立 PWA 中跨源导航时，系统会向其显示一个窗口界面，指示他们正在移出 PWA 体验。在 Chrome 中，此界面包含一个“超出范围”栏，其中包含新来源的网址。这会干扰用户体验，因为用户希望在同一应用情境中继续导航，但他们可能会认为自己被带离了该情境。

独立 PWA 顶部的范围外栏。

当用户在独立 PWA 中跨不同来源进行导航时，Chrome 中会显示“超出范围”栏。

借助范围扩展，当用户导航到任何关联的来源时，系统都不会显示窗口界面，因此 PWA 会呈现为统一的体验。

跨源链接捕获

链接捕获是指应用捕获其范围内的链接的能力。此功能的实现方式因浏览器和操作系统而异。例如，在 ChromeOS 上的 Chrome 中，已安装 PWA 范围内的链接默认会打开一个浏览器标签页，地址栏中会显示一条指示消息，表明有应用能够处理这些链接，从而允许用户从那时起选择启用自动链接捕获功能。

已安装 PWA 的 Omnibar 提示。

ChromeOS 中某个标签页的 Chrome 地址栏的片段，显示了以下内容：链接可由 PWA 处理的视觉指示，以及记住该决定的选项。

如果用户点击的链接不在 PWA 的范围内（包括指向子网域或顶级网域的链接），则不会被识别为属于该 PWA。例如，链接将在浏览器标签页中打开，而不会向用户指示有应用能够处理该链接。借助 Scope Extensions API，您可以扩展 PWA 的作用域，以便将关联的来源视为有效范围内的链接。

实现

实现范围扩展需要建立主源与关联源之间的关系。

声明关联来源的列表

向主 PWA 来源添加 scope_extensions Web 应用清单成员，以使 Web 应用能够将其范围扩展到其他来源。

Web 应用清单 (https://example.com)

{
  "name": "Example",
  "display": "standalone",
  "start_url": "/index.html",
  "scope_extensions": [
    { "origin": "https://*.example.com" },
    { "origin": "https://example.co.uk" },
    { "origin": "https://*.example.co.uk" }
  ]
}

确认关联

列出的每个来源都使用 /.well-known/web-app-origin-association 配置文件确认与相应 Web 应用的关联。此文件需要命名为 web-app-origin-association，并在此确切位置提供，因为它是 Well-Known URI。

/.well-known/web-app-origin-association（关联的源）

{
  "web_apps": [{ "web_app_identity": "https://example.com" }]
}

演示

此演示包含两个网站：

主 PWA：通过其网页应用清单中的 scope_extensions 成员声明关联来源列表的实际 PWA。
扩展范围内的来源：主要 PWA 范围之外的来源，但在被主要 PWA 列为关联来源并通过其 web-app-origin-association 文件确认关联关系后，与主要 PWA 相关联。

如需执行以下测试，您必须启用 about://flags/#enable-desktop-pwas-scope-extensions 标志（从 Chrome v115 开始提供）。

测试跨源导航

作为这些测试的前提条件，请在浏览器中打开主 PWA，将其安装为 PWA 并打开，以在独立模式下运行。PWA 包含指向扩展范围内的来源和扩展范围外的来源的链接。

包含范围内链接和扩展范围链接的主 PWA 窗口。

演示 PWA，其中包含指向扩展范围内的源站和不在扩展范围内的源站的链接。

默认的跨源导航（不在扩展范围内）

点击全屏 PWA 内的不在扩展范围内的来源链接。
因此，系统会进行导航并显示范围外栏。

点击范围外链接后，显示范围外栏的主 PWA 窗口。

默认情况下，对于以独立模式运行的 PWA 的跨源导航，系统会显示“超出范围”栏。

使用范围扩展程序（在扩展范围内）进行跨源导航

返回到 PWA 的首页。
点击指向不在扩展范围内的来源的链接。
默认情况下，系统应显示“超出范围”栏，但由于存在 Scope Extensions 关联，因此未显示。

点击扩展范围链接后，不带范围外栏的主 PWA 窗口。

在通过范围扩展程序建立来源关联后，跨源导航中不显示“超出范围”栏。

测试跨源链接捕获

在 ChromeOS 设备中打开并安装主 PWA。
点击以下链接：关联的来源。
链接会在新的浏览器标签页中打开，并显示提示，询问是否要在已安装的 PWA 中打开该链接。

具有扩展范围的已安装 PWA 的 Omnibar 提示。

点击指向 PWA 关联来源的链接会在新标签页中打开该链接，并显示“在应用中打开”图标，让用户选择是否启用自动链接捕获功能。

源试用

如果您想在实际应用中与真实用户一起测试此 API，可以通过源试用来实现。通过源试用，您可以获取与网域相关联的测试令牌，从而与用户一起试用实验性功能。然后，您可以部署应用，并期望它在支持您所测试功能的浏览器中正常运行（在本例中，该功能在 Chrome 121 至 126 中可用）。如需获取自己的令牌来运行源试用，请填写申请表单。

反馈

Chrome 团队正在征求有关此 API 实用性的反馈。为了帮助团队根据有关此 API 的实用性的反馈以及当前版本未涵盖的新使用情形来改进此 API，请在 GitHub 上提交问题。

其他资源

致谢

特别感谢此 API 的开发团队。范围扩展功能由 Alan Cutter 和 Lu Huang 指定，并征求了 Matt Giuca 的意见。该 API 由 Google Chrome 的 Alan Cutter 以及 Microsoft Edge 的 Hassan Talat、Kristin Lee 和 Lu Huang 实现。