声明式链接捕获演示 - 一键打开PWA

声明式链接捕获是 PWA 的一项能力，允许开发者通过 Manifest 文件声明式地配置应用如何响应来自外部的链接点击。当用户点击指向 PWA 作用域内（或扩展作用域）的链接时，浏览器可以根据配置决定是在 PWA 窗口中打开、创建新窗口、还是在浏览器中正常打开。

这解决了以往需要通过 JavaScript 或 Service Worker 手动处理链接路由的痛点，提供了更原生、可靠的用户体验。

• none：不捕获任何链接，所有链接在浏览器中正常打开。适合不希望 PWA 拦截链接的场景。
• new-client：每次点击链接都创建一个新的 PWA 窗口实例。适合需要多窗口并行的应用（如文档编辑器）。
• existing-client-navigate：在已存在的 PWA 窗口中导航到链接地址。适合单窗口体验的应用，避免多窗口混乱。

💡 提示：推荐配合 launch_handler.route_to 使用，以获得一致的启动和捕获行为。

scope_extensions 允许 PWA 将其链接捕获范围扩展到其他域名。例如，你的 PWA 在 myapp.com，但你也想捕获来自 partner-site.com 的链接。

使用条件：

1. 在 Manifest 中声明 scope_extensions，列出要扩展的域名。
2. 在每个扩展域名的 .well-known/web-app-origin-association 路径下放置关联文件，声明允许关联的 PWA。
3. 两个域名都必须使用 HTTPS。

⚠️ 注意：关联文件需要能通过公开 URL 访问，浏览器会定期验证。

该文件必须放在扩展域名的以下路径：https://<扩展域名>/.well-known/web-app-origin-association

例如，如果扩展域是 https://partner-site.com，则文件应可通过 https://partner-site.com/.well-known/web-app-origin-association 访问。

文件内容为 JSON 格式，包含关联应用的 manifest URL 和允许的路径范围。

🔒 该路径下的文件被视为安全敏感的配置，浏览器会严格验证其内容。

launch_handler.route_to 控制 PWA 启动时的路由行为，而 capture_links 控制运行时点击链接的捕获行为。两者配合可以实现完整的导航体验控制。

推荐配置组合：

• 单窗口应用：capture_links: "existing-client-navigate" + launch_handler.route_to: "existing-client-navigate"
• 多窗口应用：capture_links: "new-client" + launch_handler.route_to: "new-client"

截至 2024-2025 年，声明式链接捕获在 Chromium 系浏览器（Chrome、Edge、Arc 等）中得到良好支持。Android 上的 Chrome 支持尤为完善。iOS Safari 的支持正在逐步推进中。

建议在功能检测的基础上进行渐进增强，为不支持的浏览器提供优雅降级方案。

📊 可通过 navigator.userAgentData 或特性检测来判断浏览器支持情况。

1. 确保 PWA 已正确安装（在桌面或主屏幕）。
2. 打开 Chrome DevTools → Application → Manifest，检查 manifest 是否正确加载。
3. 使用 chrome://web-app-internals/ 查看已安装 PWA 的详细信息。
4. 从外部应用（如邮件、聊天工具）点击链接，观察是否在 PWA 中打开。
5. 检查扩展域的 .well-known/web-app-origin-association 是否可访问。

scope：定义 PWA 的主作用域，在同一域名下的路径范围。离开此范围的页面会退出 PWA 模式。

scope_extensions：将链接捕获能力扩展到其他域名，但需要那些域名的配合（web-app-origin-association 文件）。它不会改变 PWA 的主作用域，只是允许捕获来自扩展域的链接。

💡 简单理解：scope 管"自己家"，scope_extensions 管"邻居家"（需要邻居同意）。