此页面由 Cloud Translation API 翻译。

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 应用，此类网站架构会产生影响。局限性包括无法跨源共享 Service Worker、任何类型的设备、本地存储空间和权限。此外，独立 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 和相关子体验的示意图。

当涉及到 Web 应用界面时，范围扩展允许多源 PWA 像连续 Web 应用一样运行。

实际上，这可转化为两个更具体的目标：

跨域导航：通过调用窗口界面来通知用户正在离开 PWA，让用户能够在关联的源站之间导航，而不干扰用户体验。
跨域链接捕获：允许 Web 应用捕获用户转到与其关联的网站的过程。

范围内的跨域导航

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

独立 PWA 顶部的“超出范围”栏。

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

使用范围扩展时，当用户导航到任何关联的源站时，系统不会显示窗口界面，因此 PWA 可以提供统一的体验。

跨源链接捕获

链路捕获是指应用在其范围内捕获链接的能力。实现方式因浏览器和操作系统而异。例如，在 ChromeOS 上的 Chrome 中，安装的 PWA 范围内的链接默认会打开一个浏览器标签页，并在地址栏中指示有应用可以处理这些链接，以便用户选择从该位置开始自动捕获链接。

Omnibar 提示要求已安装 PWA。

ChromeOS 中标签页的 Chrome 地址栏片段，其中以视觉方式指示链接可由 PWA 处理，并提供用于记住该决定的选项。

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

实现

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

声明关联源的列表

将 scope_extensions Web 应用清单成员添加到主 PWA 源，使 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 并在确切位置提供，因为它是一个众所周知的 URI。

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

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

演示

该演示包含两个网站：

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

如需执行以下测试，您必须启用 about://flags/#enable-desktop-pwas-scope-extensions 标志（适用于 Chrome v115 及更高版本）。

测试跨源导航

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

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

演示 PWA，使其在扩展范围内链接到源站，而不是在扩展范围内链接到源站。

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

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

点击“范围外”链接后，显示“不在范围内”栏的主 PWA 窗口。

默认情况下，独立模式下 PWA 的跨源导航会显示“超出范围”栏。

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

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

点击扩展范围链接后，没有“超出范围栏”的主 PWA 窗口。

与范围扩展建立源站关联后，跨源导航中不显示“超出范围”栏。

测试跨源链接捕获

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

Omnibar 提示显示了已安装扩展范围的 PWA。

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

源试用

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

反馈

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

其他资源

致谢

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