UD5工具箱
使用教程
本教程将详细介绍如何使用 URL 协议处理演示工具来配置 PWA 的 Protocol Handlers 功能。请按照以下步骤操作：
第一步：理解 Protocol Handlers 的工作原理
在开始配置之前，了解 Protocol Handlers 的工作原理非常重要。当用户点击一个协议链接（如 web+myapp:some/data）时，操作系统会查找已注册的处理程序。如果用户的设备上安装了声明了该协议的 PWA，浏览器会弹出确认对话框询问用户是否允许使用该 PWA 打开此链接。用户确认后，PWA 会导航到 manifest 中配置的处理页面，并通过 URL 参数传递编码后的原始协议 URL。
第二步：配置协议名称
在"协议处理器配置"区域，首先输入或选择协议名称。如果您需要使用自定义协议，建议使用 web+ 前缀（如 web+myapp），这是 Web 应用保留的自定义协议命名空间，可以避免与系统预设协议冲突。如果您只需要处理常见的协议类型，可以从下方的预设按钮中快速选择，包括 mailto（邮件）、tel（电话）、webcal（日历）等。
第三步：设置 URL 处理模板
接下来配置 URL 处理模板，这是 PWA 接收到协议 URL 后导航到的页面地址。模板中必须包含 %s 占位符，该占位符在运行时会被替换为经过 URI 编码的完整协议 URL。例如，您可以设置为 /handle-protocol?url=%s，这样当用户点击 web+myapp:path/data?id=1 时，PWA 会导航到 /handle-protocol?url=web+myapp%3Apath%2Fdata%3Fid%3D1。您还可以在模板中添加固定的查询参数（如应用标识符），用于在处理页面中区分不同的协议来源。
第四步：填写应用标题（可选）
应用标题字段是可选的，用于在浏览器权限提示中显示的应用名称。如果填写了标题，用户在首次确认协议处理权限时会看到更清晰的应用标识信息，有助于提升用户体验和信任度。
第五步：生成并复制配置
完成上述配置后，点击"生成 Manifest 配置"按钮，工具会自动生成包含 protocol_handlers 配置的 JSON 代码片段。您可以在下方的"Manifest 预览"区域查看生成的代码，并点击复制按钮将其复制到剪贴板。然后将这段配置添加到您项目的 manifest.json 文件中。
第六步：实现 PWA 处理页面
接下来，您需要在 PWA 中创建协议处理页面。该页面需要实现以下逻辑：首先从 URL 查询参数中获取编码的协议 URL；然后使用 decodeURIComponent() 还原原始 URL；最后解析协议名称和路径数据，执行相应的业务处理。工具提供了完整的 JavaScript 代码示例，您可以直接参考使用。
第七步：测试协议处理功能
配置完成后，可以通过以下方式测试协议处理功能：首先确保 PWA 已正确安装（需要 HTTPS 环境）；然后创建一个包含协议链接的测试页面（如 <a href="web+myapp:test">测试链接</a>）；在浏览器中点击该链接，观察是否弹出协议处理确认对话框；确认后检查 PWA 是否正确接收并处理了协议 URL。您也可以在 Chrome 中访问 chrome://settings/content/handlers 查看已注册的协议处理程序。
第八步：检查浏览器兼容性
在正式部署之前，建议使用工具的浏览器能力检测功能检查目标浏览器的支持情况。目前 Chrome 96+ 和 Edge 96+ 提供了完整支持，Opera 82+ 也支持该功能。Safari 目前不支持 manifest protocol_handlers，Firefox 的支持相对有限。对于不支持的浏览器，建议提供降级方案或替代入口。
第九步：关注安全最佳实践
在生产环境中使用 Protocol Handlers 时，请务必关注安全事项。始终验证传入的协议 URL 是否来自可信来源；设置 URL 白名单限制可处理的协议和路径模式；对解码后的 URL 进行严格的输入验证和消毒处理；避免直接将协议 URL 插入 DOM 以防止 XSS 攻击；确保 PWA 和协议处理均在 HTTPS 环境下运行。