创建 Safari Web Inspector 扩展

♪ ♪ Devin Rousso: 大家好 我是 Devin Rousso WebKit 团队的一名工程师 今天我想在这里与你分享 一个激动人心的新机会 为 Safari 浏览器的 Web Inspector 创建扩展 Web Inspector 是在所有 Apple 平台上 调试网络内容的主要开发工具 它已经有了大量 用于调试网站的内置功能 但是通常网络开发的一些领域 很难构建成一个通用的开发工具 也许你正在调试 一个流行的 JavaScript 库 或者你只是需要一些更具体的东西 Web Inspector 扩展是这些 个人工作流程场景的 绝佳解决方案

通过利用跨浏览器网络扩展 和 DevTools APIs 你现在可以在 Safari 16 的 Web Inspector 中添加自己的标签 我们来快速浏览一下 Web Inspector 扩展 然后我将向你展示 如何构建自己的扩展 首先我将打开 Safari 浏览器的扩展偏好设置

并启用 Web Inspector 扩展 然后我会关闭 Safari 浏览器的 扩展偏好设置并检查页面

我将从开发菜单中选择 显示 Web Inspector 在 Web Inspector 中 我不仅可以看到许多内置的选项卡 如 Elements Tab 还可以看到我刚刚启用的 Web Inspector 扩展的选项卡 因为我们刚刚启用了这个扩展 但是我们首先必须给它权限 来处理当前检查的页面 我有和 Web Inspector 之外的 其他扩展相同的权限持续时间选项 所以现在让我们给它一天的访问权限 我将在本期讲座中 构建这个 Open Graph 扩展 它显示大多数网站放在页面上的 常见社交媒体元数据 通过 Messages 和其他社交媒体网站的链接 预览使用 现在我们已经快速了解了 Web Inspector 扩展的功能 让我们来谈谈它们是如何构建的 与其他 Safari Web 扩展一样 Web Inspector 扩展 通过 App Store 中的 App 来分发

要构建自己的 Web Inspector 扩展 你需要有 Xcode 这是 Apple 用于构建 Mac 和 iOS app 的应用程序创建工具 Xcode 还附带项目模板 以帮助快速制作 新的 Safari 浏览器扩展 App 如果你已经有了为另一个浏览器 创建的现有网络扩展 你也可以使用 Xcode 的 捆绑转换工具 只需从终端运行 safari-web-extension-converter 传递包含 manifest.json 文件的 扩展目录的路径 然后将为你的扩展 创建一个完整的 App 项目 并准备好构建和运行

有关此工具的更多信息 请查看 WWDC 2020 中的 Meet Safari Web Extensions 以及在线文档 因此 今天我将介绍 Web Inspector 扩展的基本结构 介绍如何最好地评估该扩展中的代码 并讨论一些适合用户的最佳实践 我们开始吧

Web Inspector 扩展的结构 与其他 Safari Web Extension 一样 有工具栏图标 背景页 内容脚本等 但它们也有专用的开发工具背景页 我们来看看它在实践中是如何工作的 典型的 Safari Web 扩展的结构 从一个清单文件开始 该文件声明了扩展的 基本细节 如名称 图标 描述等 它可以声明一个背景页来处理 你的扩展程序的 所有幕后逻辑 还可以声明任何用于将功能注入到 用户访问网页中的内容脚本 对于 Web Inspector 扩展 还有一些其他的页面 首先有一个必需的开发工具背景页 用于 Web Inspector 扩展的幕后逻辑 该页面可以访问独特的开发工具 API 和有限的内容脚本 API 从这个开发工具背景页 你可以创建在 Web Inspector 中 显示的开发工具选项卡页面 但所有这些都只是针对 单个 Web Inspector 如果有多个 Web Inspector 每个都有自己的 相同的开发工具背景页实例 在相关 Web Inspector 打开期间 保持活动状态 因此 每个开发工具选项卡页面 也可能有多个实例 我们来看看这种结构 在实践中是怎样的 并开始构建我的 Open Graph Web Inspector 扩展

首先我会在 Xcode 中创建一个新项目

我要创建的项目类型是 Safari Extension App 我只需要 macOS 但我会让它在多平台中保持原样 以防我将来想添加 iOS 功能 我会把它命名为 Open Graph 并保留其余的默认值 请注意 你需要根据 你使用的 Apple 开发者帐户 选择一个团队和捆绑包标识符 最后 我把它保存在桌面上

现在我有了一个通用的 Safari Web 扩展项目 可以随时修改 我首先进入 manifest.json 文件 这是每个网络扩展的根配置文件 清单文件引用 构成扩展程序的其他资源 本地化 图像 页面 脚本 样式等 对于我的 Web Inspector 扩展 我不需要其中的一些文件 如背景页 内容脚本或弹出窗口 所以我会从清单和整个项目中 删除它们

好的 让我们开始把它 变成一个 Web Inspector 扩展 为此 我需要将开发工具背景页 添加到清单并为其创建相应的文件 以及我会在其中使用的 JavaScript 文件 我将点击 File New File

向下滚动找到 Empty 文件模板

我将此文件命名为 devtools_background.htm 以匹配我在清单中使用的名称

该位置已经设置在我的其他资源 和部分正确目标的旁边 所以我不需要在这里做任何更改

我将再次对 JavaScript 文件 重复相同的步骤

我将其命名为 “devtools_background.js”

最后 我需要在我的开发工具 背景页中包含 JavaScript 文件

请记住 此页面是在 Web Inspector 打开时创建的 负责创建出现在 Web Inspector 中的自定义选项卡 我几乎总是想创建一个选项卡 这样 如果有需要的话 我之前 看到的权限将在线显示给我的用户 而不是在其他地方 这个开发工具面板创建 API 需要三个简单的参数 第一个是选项卡的名称 为此 我使用本地化方法来查找 扩展的本地化名称 下一个参数是要拿来使用的图标路径 请注意 如果用户选择 缩放他们的用户界面 这应该是一个矢量图像 以便平滑地缩放到任何大小 但是为了使用这个图标 我需要确保它是我项目的一部分 还有我的扩展需要的所有其他图标 “图像”文件夹中的图标 仍然是项目模板中的默认图标 因此让我们从项目中删除这些内容

用我之前创作的一些图标来代替它们

包括我在创建开发工具选项卡时 尝试使用的 logo.svg

现在 我将返回到开发工具后台脚本

第三个参数是 Web Inspector 中 选项卡使用的 HTML 就像刚才的图片一样 我需要创建这个页面才能使用它

我将此命名为 devtools_tab.html 以匹配我给 API 起的名称

然而 与开发工具背景页不同 这个开发工具选项卡页面 实际上会显示给用户 所以这次我将创建 一个 JavaScript 和 CSS 文件

我将这个 JavaScript 文件 命名为 devtools_tab.js

CSS 文件命名为 devtools_tab.css

很好 我已经设置了这个结构 但现在我只添加常用的 Hello World 来确保一切正常运行 但别担心 我们稍后会 更深入地讨论这个问题 因为首先 我们还有几个图标要替换 以确保此扩展具有一致的外观 首先我们需要替换默认的大图标

删除它

并将我的大图标拖到原来的位置

但是由于这个大图标是 App 的一部分 因此我需要把它添加到正确的目标中

其余图标都是资产目录的一部分 特别是 AppIcon 集

我已经准备好这些图标 所以我将它们粘贴进去 我认为我们已经替换了所有默认图标 所以现在要运行我的扩展程序 请注意 在第一次构建项目时 运行可能需要几秒钟时间

就是这样 这个 UI 的大部分来自 Xcode 模板 但是我确实看到了我的图标 而不是默认图标 只要启动了至少一次 Safari 浏览器扩展应用程序 我们就可以把它关闭 因为 Safari 浏览器不需要 再运行该 App 来启动它

但是在 Safari 浏览器中看到它之前 我必须在 Develop 菜单中 允许未签名的扩展 因为这是一个本地构建的未签名 App 现在 在 Safari 浏览器的扩展首选项中 我可以看到 Open Graph 我把它打开 我将打开一个 Safari 浏览器选项卡 并浏览至 apple.com 这样我就可以尝试我的扩展程序 已经可以看到我的图标在工具栏中

我的扩展选项卡现在在选项卡栏中 切换到这里 我们可以看到跟之前看到的 相同的权限提示 如果扩展需要权限 则会自动显示此权限提示 就像之前一样 我给它一天时间

还有我之前添加到 开发工具标签页的 Hello World 以上就是如何为 Safari 16 创建 Web Inspector 扩展的基础知识 我们来回顾一下 我声明了开发工具的背景页 并将其添加到我的 Xcode 项目中 从那里 我能够在 Web Inspector 中 创建新的选项卡 来显示我的定制工具 最后 我开始考虑扩展所需的权限 对于 Web Inspector 扩展 这通常归结为 评估被检查页面中的代码 通常是提取一些数据 以在 Web Inspector 中显示 Web Extension 已经有许多 评估代码的方法 对于 Web Inspector 扩展 还有另一个 API 是评估 被检查页面内脚本的首选方法 我们来看一下这个 API 看看如何 将它用于我的 OpenGraph 扩展 这个开发工具扩展 API 在被检查的窗口中评估 JavaScript 是快速获得结果的最佳方式 它将自动定位 与运行扩展的 Web Inspector 相关联的页面 记住 用户可以同时检查多个页面 这个 API 还有一些有用的选项 可以帮助你获得正确的结果 默认情况下 这个 API 的表达式 是在被检查页面的主框架的 上下文中计算的 但是你可以使用 frameURL 选项 在不同的框架内指定评估 当你的扩展需要从页面中 许多可能的子框架之一提取数据时 这是必需的 对于我的 OpenGraph 扩展 我只需要担心主框架 但是我建议你在评估 Web Inspector 扩展的脚本时 记住这一点 我们来看看如何在我的扩展中 使用这个函数来获取和显示 被检查页面的数据 我将首先用 HTML 替换 我之前添加的占位符 Hello World 它实际上加载了 我的 CSS 和 JavaScript 文件

然后我将添加一些基本的 CSS 来给 开发工具选项卡一个漂亮的样式

我想确保我的开发工具选项卡 与 Web Inspector 的其余部分相适应 因此我声明了一个“颜色方案”的根属性 该属性使我的开发工具选项卡与 Web Inspector 其余部分外观相匹配 使用系统字体系列并继承字体大小 并匹配更重要文本的颜色 至于功能 我将从添加一些文本开始 以防页面没有任何 opengraph 元数据 请注意 我可以在 Web Inspector 中 使用 Web 扩展本地化字符串 就像我在 Web 扩展的其他地方 可以做到的一样 但为了做到这一点 我需要将相同的本地化字符串标识符 添加到本地化字符串文件中

接下来 我将创建提供给功能强大的开发工具 devtools-inspectedWindow-eval API 的 JavaScript 这让我在检查过的页面中 对其进行评估 在本例中 我想查询被检查页面的 DOM 以查找一些常见的 opengraph 元数据 特别是标题 描述

和图像 以及被检查页面文档的当前就绪状态 将其捆绑在一起 通过返回值发送回开发工具页面 完成后 我可以获取对应于 每个属性的 HTML 元素 并对其进行配置 以便它们显示收集的数据

如果文档还没有准备好 我可以稍等片刻后再试一次

我还想在每次检查页面导航时 重复所有这些操作 因此我将为 开发工具网络 onNavigated 添加一个侦听器

这一切看起来都很棒 所以我将再次构建来测试它

现在每当我打开 Web Inspector 或在 Web Inspector 已经打开的情况下导航时 我都可以看到每个页面的 opengraph 标题 描述和图像 这是一个简单的示例 展示了如何使用许多新的 强大的 Web Inspector 扩展 API 我的 OpenGraph 扩展 进展得很顺利 我的 Web Inspector 扩展的 开发工具标签页 现在可以在被检查的页面中进行评估 我能够获取结果数据并对其进行处理 以用户友好的格式显示出来 以便快速访问 那么在创建 Web Inspector 扩展时 有哪些好方法可以让用户体验更好呢 始终从开发工具后台页面 创建开发工具选项卡页面 这样用户可以看到这些选项卡将 出现在 Web Inspector 中的什么位置 并且任何适当的权限提示 都将内嵌显示 与其要求特定的主机权限 不如尝试使用 activeTab 权限 来尽可能有针对性地 保持 Web Inspector 扩展 并确保使用 CSS 颜色方案属性 或 Web 扩展开发工具主题 API 来匹配 Web Inspector 的整体主题 今天我向你展示了如何使用 Web Inspector 扩展 来创建全新的调试工具 并介绍了一些在这样做时 要牢记的最佳实践 如果你想更深入地了解自己 欢迎你在本讲座的相关资源中 下载 OpenGraph Web Inspector 扩展

我们非常想听听你的想法 所以请使用反馈助手 提交错误和功能请求 或者在 Safari 浏览器开发者论坛上 与我们聊天 甚至可以考虑加入 WebExtensions 社区团体 来帮助塑造网络扩展的未来

此外请务必查看 What's new in Safari Web Extensions 以及在线文档 以了解今年更多的新增功能 我真的希望你喜欢学习 在 Web Inspector 中 创建自定义工具的惊人的新功能 我们迫不及待地想看到你将会创造出 多么棒的 Web Inspector 扩展 并期待你以各种方式突破可能的界限 非常感谢你的收听 希望你余下的 WWDC 之旅精彩无限