创建 Safari 浏览器的网页扩展

创建 Safari 浏览器的网页扩展

从零开始构建并测试 Safari 浏览器网页扩展，放心迈出入门第一步，而且全程无需使用 Xcode。探索内容拦截、页面修改、原生通信和权限模式如何协同工作，跨平台打造强大且保护隐私的浏览体验。

章节
- 0:00 - Introduction
- 3:23 - Get started
- 7:23 - Block content
- 14:40 - Modify webpages
- 19:53 - Package and distribute
- 22:33 - Communicate with your app
- 26:04 - Next steps
资源
相关视频

WWDC26
- 面向 Safari 浏览器 27 的 WebKit 新功能
你好!
我是Kiara 一名来自 Safari团队的工程师如果你曾有过想在Safari 中看到的功能想法并且想将这个想法变为现实这节课就是为你准备的我将带你了解构建和分发所需了解的一切 Safari网页扩展的全部知识内容很多你可以随时休息或跳到最相关的章节对你最有用的部分 Safari网页扩展封装在一个App中说实话这是我最喜欢从App Store获取的东西之一无论是屏蔽广告还是构建自定义新标签页还是在你最喜爱的流媒体平台上提升播放体验它们虽小却能切实改善你浏览网页的体验 Apple正在W3C网页扩展工作组中与其他浏览器合作以标准化跨浏览器构建网页扩展所用的API 因此如果你已为其他浏览器开发了扩展就可以将扩展迁移到Safari 跳转到打包与分发章节我将展示如何使用App Store Connect 发布你的扩展今天我将全面讲解如何从零开始构建一个网页扩展我将带你了解扩展的开发流程并重点介绍可用于在Safari中带来可定制体验的关键API和功能我还将展示如何在Safari中测试网页扩展以及如何使用 TestFlight与用户分享扩展的Beta版本一旦我准备好与世界分享我的作品我将提交扩展到App Store 首先下载本节课的示例代码项目其中包含我今天将要构建的扩展的所有资源这样你就可以跟着一起做了在本节课中我将带你构建一个真实的扩展一个能屏蔽内容并修改网页的扩展然后我将介绍几种不同的打包方式供你选择并将扩展发布到App Store 为了让扩展功能更强大我将展示如何让扩展与包含它的App 协同工作最终这个扩展将同时在 iOS iPadOS macOS上的Safari运行以及visionOS上因为网页扩展的魅力在于它们全都由 HTML CSS和JavaScript组成所以如果你之前做过任何Web开发你已经掌握了大部分所需知识在今天的课程中我将构建一个允许用户屏蔽分散注意力的网站让他们专心浏览网页的扩展如你所知浏览时有很多令人分心的"兔子洞" 以webkit.org为例那里有数百篇文章我很容易就会花上好几个小时只是阅读WebKit的新内容所以我需要这样一个扩展今天我要构建它它有两种不同的屏蔽模式一种轻量模式允许在某个网站上浏览最多10分钟非常适合阅读几篇WebKit文章还有一种完全模式会在用户尝试时立即重定向跳转到该网站首先我打开我最喜欢的代码编辑器你也可以使用Xcode 但任何编辑器都可以构建扩展在代码编辑器中我将创建一个文件夹存放所有文件打好基础每个扩展首先需要的是一个清单文件清单是一个JSON格式的文件用于告知浏览器扩展的信息以及它能做什么可以把清单想象成你扩展的身份证它包含各种信息例如扩展的名称描述和版本号接下来我将添加一个存放扩展图标的图片文件夹图标可以出现在各种不同的地方比如工具栏... 或扩展设置根据显示位置的不同需要不同尺寸的图标所以我将以SVG格式添加图标 Safari会完美处理图标缩放让我专注于重要的事情比如打开代码编辑器展示实际效果在清单文件中我已添加了扩展的图标图标位于我的图片文件夹中为了查看效果我保存更改然后前往Safari 来加载扩展在Safari中加载扩展非常简单只需使用Command+逗号打开Safari设置点击高级设置面板并勾选 "显示适用于网页开发者的功能" 这将启用开发者面板然后我就可以添加一个临时扩展由于这个扩展尚未经过代码签名验证我需要允许未签名扩展允许后我选择包含扩展资源的文件夹就这样我的扩展已加载到Safari中了! 大多数扩展都会有某种供用户交互的UI 对于我的扩展我希望让用户能够添加分散注意力的网站到屏蔽列表所以我需要添加一些自定义UI 有几种方式可以实现一种方式是使用扩展的操作按钮这是在Safari工具栏中为扩展添加的按钮点击后 Safari会显示弹出窗口展示你为其定义的UI 弹出窗口的文件名或清单中定义的任何资源可以是任何你想要的名称只要与正确的清单键关联让Safari知道它是什么以及如何使用它在这个示例中加载默认弹出窗口的文件设置为"popup.html" 对于我的扩展在弹出窗口中显示屏蔽列表可能会让UI看起来有些拥挤所以我将使用扩展的选项页面来显示这将是一个完整页面用户可以在此设置扩展选项现在我将回到代码编辑器添加这个更改在清单中我已定义了选项页面我将在扩展文件夹中为它添加一个文件在添加此页面的完整UI之前我先从简单的内容开始比如Hello World 在Safari中我可以通过重新加载扩展来测试更改太棒了! 我的新更改生效了扩展现在有了这个设置按钮点击该按钮会打开我扩展的选项页面! 设置好之后我的扩展还需要做更多而不仅仅是显示"Hello World" 才能真正发挥作用所以我设计了一个页面允许用户在轻量模式和完全模式之间切换我已经使用HTML CSS和JavaScript 编写了这个界面看起来很漂亮也很互动但我需要将它连接起来现在我将了解如何升级扩展以开始屏蔽内容我将使用声明式网络请求API 它将赋予我的扩展屏蔽修改或重定向网络请求的能力这个API驱动着我最喜欢的那类网页扩展有了这种能力扩展可以过滤广告等网页内容以及在用户浏览网页时针对他们的追踪器但为了让我的扩展访问这些功能我需要为它添加一个权限权限是扩展告知Safari 所需访问权的方式比如访问Cookie 将数据保存到存储或写入剪贴板对于内容屏蔽我需要添加声明式网络请求权限我可以在扩展的清单中完成这一步设置好之后我就可以开始定义规则了一条规则具有ID 优先级以及满足条件时应触发的操作类型当条件满足时例如这条规则会屏蔽所有前往webkit.org的导航有两种方式可以定义规则一种方式是在清单中定义它们这些称为静态规则当你已经知道要使用哪些规则时非常适用但如果需要一些灵活性你可以在运行时动态添加规则使用JavaScript 我将选择动态方式因为我不知道要屏蔽哪些网站直到用户将它们添加到列表中我将把这个逻辑放在 utilities文件夹中的rules.js文件里然后我将使用host.js文件来创建规则当用户将网站添加到屏蔽列表时我将回到代码中连接这些逻辑在扩展的清单中我已添加了声明式网络请求权限我还将之前的选项页面替换为 HTML CSS和JavaScript文件这些是我已经为扩展创建的文件我还添加了包含两个新文件的utilities文件夹要添加规则我前往rules.js文件由于这些规则需要指定ID 我添加了一个辅助方法将网站的主机映射到唯一的整数ID 现在我创建一条规则指定ID 类型为"block" 以及urlFilter 来匹配网站的主机然后使用声明式网络请求的 updateDynamicRules API 将规则添加到我的扩展在我的host文件中当网站被添加到列表时如果扩展处于完全屏蔽模式就可以添加规则回到Safari 我重新加载以更新扩展
在选项页面我将webkit.org添加到列表
当我访问该网站时它被屏蔽了! 我的扩展现在可以屏蔽对列表中网站的导航了但我不太喜欢那个弹出的错误页面我更希望将用户引导到更有意义的地方比如自定义页面一个我为扩展专门设计的页面这就是重定向规则发挥作用的地方这条规则与之前的屏蔽规则类似但类型是重定向我可以指定extensionPath 作为用户将要进入的页面但在进行这个更改之前我需要为扩展添加主机权限要屏蔽网络请求扩展不需要访问页面但对于重定向网络请求扩展确实需要访问权限所以在扩展的清单中我将使用 declarativeNetRequestWithHostAccess 权限代替由于我的扩展不需要预先请求任何网站的访问权限我可以使用可选主机权限并在运行时请求网站访问权主机权限告知Safari 你的扩展想访问哪些网站你可以将它们设置为一组匹配模式每个模式由协议主机和路径组成由于任何网站都可以被添加到列表我将使用一个可以匹配所有URL的模式如果你的扩展需要明确访问某个网站才能运行可以改用主机权限但扩展不会自动获得对该网站的访问权我们为扩展设计了权限模型以尊重用户隐私由于用户的浏览体验可能会暴露个人数据我们让用户掌控由他们决定扩展可以访问哪些网站如果你明确请求访问权限 Safari会在扩展的操作按钮上显示徽章点击该按钮会弹出提醒询问用户是否要授予扩展访问该页面的权限如果用户选择允许访问图标将变为彩色通知他们扩展在该页面处于活跃状态我的扩展不需要预先访问任何网站这就是我选择可选主机权限的原因这样我的扩展需要时就可以请求任何网站的访问权在清单中我已将权限更改为 declarativeNetRequestWithHostAccess 我的扩展现在可以在运行时请求访问任何网站了现在在规则文件中我将创建重定向规则它与之前的屏蔽规则非常相似但现在类型是重定向并且包含指向我自定义扩展页面的路径我还在扩展文件夹中添加了该页面的资源现在不再屏蔽导航而是将用户重定向到一个页面一个我为扩展设计的页面由于扩展需要访问该网站我将请求访问权限使用permissions.request API 请求访问该域名及其子域名为了查看这种体验我将在Safari中更新扩展
在选项页面中我将添加webkit.org
现在在网站被添加之前我收到提示要授予扩展访问权限很好! 这正是我所期待的我允许访问并刷新页面
太棒了! 导航被重定向到我的自定义扩展页面我的扩展进展得真好! 它现在可以将前往干扰性网站的导航重定向了但说实话与一些你最喜欢的网站完全断联可能很难所以我将添加一个允许浏览最多10分钟的模式并在页面上显示倒计时为了实现这一点我需要一种直接将内容注入页面的方式这就是内容脚本发挥作用的地方内容脚本赋予扩展读取和修改的能力网页内容脚本可以是静态的直接在清单中声明包含它们将运行的网站的文件和匹配模式如果你已经知道要针对哪些网站这很有效但在我的情况下直到网站被添加到列表我才知道所以我将动态添加它们使用注册内容脚本API 这些与静态脚本完全相同但有两个额外字段一个ID和一个持久化标志将此设置为true意味着脚本将保留在Safari重新启动之后要使用此API 我将在清单中添加scripting权限以及在utilities文件夹中添加新的scripting.js文件在这里我将定义内容脚本我将给它一个ID 计时器的JavaScript文件样式的CSS 以及覆盖该网站域名和所有子域名的匹配模式然后我将此标志设置为true 接着我将使用注册内容脚本API添加脚本回到我的addHost方法现在当用户将网站添加到屏蔽列表时我将添加一个内容脚本来为该网站显示计时器当扩展处于完全屏蔽模式时重定向会在页面加载前触发所以我可以始终注册脚本现在选择轻量屏蔽模式我将webkit.org添加到列表当我访问该网站时页面上会显示10分钟的计时器
我的扩展离我想发布到世界的版本已经非常接近了但有一件事我想先修复正如你可能注意到的每次我重新加载扩展我都必须重新将同一个网站添加到列表这是因为我将所有信息存储在内存中当扩展重新加载时该状态就消失了
我可以使用storage API 来保留这些数据 Safari支持两种存储区域 Session Storage适合快速的内存操作不需要在重启后保留的数据但我希望我的屏蔽列表持久保存所以Local Storage （将数据写入磁盘）是正确选择
要使用storage API 我将在清单中添加权限然后我将在 utilities文件夹中添加一个新文件在此文件中我将定义几个辅助方法用于更新和获取存储中的主机以及几个用于保存和获取屏蔽模式的方法
回到我的addHost方法现在当用户添加新网站时我可以更新存储中的主机列表我还可以使用存储的列表来显示屏蔽列表有了这个更改屏蔽列表将始终显示所有已添加网站的完整列表! 同样地当用户在两种模式之间切换时我将把更改保存到存储如果扩展处于完全屏蔽模式我可以为所有网站创建重定向规则为了看到storage API的效果在Safari中我将屏蔽模式改为"Full" 并将一个网站添加到列表
现在当我重新加载扩展时我刚才做的更改仍然保留! 很好! 使用storage API解决了扩展的一个持久化问题但还有另一个问题需要解决已注册的内容脚本在Safari重启后仍然保留但在扩展更新后则不会所以如果用户更新了我的扩展他们将失去内容脚本为了解决这个问题我需要让扩展知道它已被更新这样它就可以从存储中读取主机并重新创建脚本最佳位置是在后台页面或Service Worker中两者都可以做相同的事情比如管理扩展的生命周期监听浏览器事件并在扩展的各个部分之间传递消息 Safari同时支持这两种所以完全取决于你的偏好! 我喜欢后台页面因为它们可以访问DOM 所以我选择它要添加后台页面我将在清单中指定它然后我将文件添加到扩展文件夹中在这里我将注册 onInstalled事件这将让我的扩展知道它已更新到新版本当这种情况发生时我将从存储中读取主机并重新注册内容脚本让扩展能够从存储中读写数据带来了巨大的改进我认为是时候看看如何将扩展发布到App Store了一种方式是使用 App Store Connect App Store Connect是你可以上传提交和管理扩展的地方无论你是刚构建好自己的扩展还是想将现有扩展迁移到Safari 最棒的部分呢? 你可以在任何浏览器中完成这些操作无需使用Mac 首先我前往 developer.apple.com并注册 Apple Developer Program 注册后我前往 appstoreconnect.apple.com 由于Safari网页扩展需要封装在一个包含App中我可以使用App Store Connect 为我创建这个App 创建App时我需要指定一些内容例如我想让扩展在哪些平台上可用我将选择iOS和macOS 这将使我的扩展在iPhone iPad Mac上可用以及作为Apple Vision Pro 上的兼容App 我还将设置Bundle Identifier 这是我App的唯一ID 添加所有详细信息后我将切换到Xcode Cloud标签向下滚动到 Safari网页扩展打包程序上传我扩展的资源上传完成后 Safari网页扩展打包程序将在几分钟内完成打包我的扩展! 完成后我可以查看任何问题或采取后续步骤测试扩展使用TestFlight TestFlight允许我分发Beta版本这样我可以持续改进并收集用户反馈然后再将扩展提交到App Store 一旦我准备好提交我将前往发布标签添加最后的细节比如扩展运行中的截图以及帮助用户了解的描述我扩展的功能和特性添加所有详细信息后我将选择构建版本并提交审核这就是如何使用 App Store Connect分发扩展的方法! 在本节课中我展示了标准WebExtension API和功能如何共同构建可定制的浏览体验但如果我告诉你你的扩展可以超越网页平台呢我将引导你了解如何使用原生消息传递来访问功能这些平台提供的功能从这里我需要使用Xcode 最简单的方式是使用 Safari网页扩展打包程序工具在Terminal中运行此命令将为我创建并启动一个Xcode项目它将包含我的App和网页扩展然后我可以将它们连接起来发送和接收消息我们称之为原生消息传递把它想象成三个人传递便条我扩展中的JavaScript 开始发起中间的App Extension 接收该消息并将其传递给原生App 然后App执行操作并以相同方式将结果发送回来对于我的App 我将让它帮助扩展保护设置在对屏蔽列表进行更改前要求生物识别认证首先我将添加 nativeMessaging权限在我扩展的清单中然后在扩展的后台页面中我将添加一个方法来发送消息从我的扩展发送到其原生App 我收到的消息将告知我认证是否成功为了让我的App 接收消息我需要修改 SafariWebExtensionHandler 一个包含在打包程序工具为我创建的文件中的类棒的是它附带一个模板已经允许我的App 从我的扩展接收消息我需要做的只是几处调整比如解析消息中的 requestBioAuth键然后我将使用系统API 请求用户生物识别认证一旦用户完成认证 App将消息发送回来将结果传递给网页扩展我将进入Xcode构建扩展并在Safari中测试更改在Xcode中我已完成向扩展发送和接收消息的更改在Project Navigator中我的项目包含了网页扩展的所有资源我将使用Command+B快捷键构建扩展在Safari中我启用扩展打开选项页面并将webkit.org添加到列表
在添加之前我收到提示通过触控ID认证认证后网站被添加到列表中这就是如何使用原生消息传递让App 和网页扩展协同工作有了这些我可以自豪地说我的扩展已准备好分发了我将使用Xcode来完成
我将先构建一个归档文件由于我之前使用 App Store Connect创建了一个构建版本我需要确保这个构建版本号比上一个高一步在Organizer窗口中我将分发扩展这就是如何从零开始创建和分发Safari网页扩展的方法从零开始今天我们涵盖了很多内容无论你是刚刚起步还是想进一步拓展扩展功能我希望你已经准备好将想法转化为现实我迫不及待地想看到你构建的作品
如果你还没有的话下载示例代码项目来玩玩今天介绍的一些API 你可以通过查看跨浏览器文档来进一步了解 MDN上关于网页扩展的文档最后通过Feedback Assistant 提供反馈或在bugs.webkit.org上提交Bug 当你在Safari 27上测试网页扩展时感谢你与我一起踏上这段旅程 WWDC快乐!

{
    "manifest_version": 3,
    "name": "Shiny OnTrack",
    "description": "Stay on track while you browse the web",
    "version": 1.0
}

4:29 - Adding an extension icon

{
    "manifest_version": 3,
    "name": "Shiny OnTrack",
    "description": "Stay on track while you browse the web",
    "version": 1.0,

    "icons": {
        "512": "images/icon.svg"
    }
}

5:30 - Adding an action button

{
    "manifest_version": 3,
    "name": "Shiny OnTrack",
    "description": "Stay on track while you browse the web",
    "version": 1.0,

    "action": {
        "default_popup": "popup.html"
    }
}

6:17 - Adding custom UI to your extension

{
    "manifest_version": 3,
    "name": "Shiny OnTrack",
    "description": "Stay on track while you browse the web",
    "version": 1.0,
  
    "options_ui": {
        "page": "options.html"
    }
}

6:30 - Including the UI in the extension manifest

{
    "manifest_version": 3,
    "name": "Shiny OnTrack",
    "description": "Stay on track while you browse the web",
    "version": 1.0,

    "icons": {
        "512": "images/icon.svg"
    },

    "options_ui": {
        "page": "options.html"
    }
}

6:40 - Hello World

<!DOCTYPE html>
<html>
    <body>
    <p>Hello World</p>
    </body>
</html>

8:18 - Adding declarativeNetRequest permission

{
    "manifest_version": 3,
    "name": "Shiny OnTrack",
    "description": "Stay on track while you browse the web",
    "version": 1.0,

    "icons": {
        "512": "images/icon.svg"
    },

    "options_ui": {
        "page": "options.html"
    },
  
    "permissions": [ "declarativeNetRequest" ]
}

8:22 - Blocking network requests

// block rule
{
    id: 1,
    priority: 1,
    action: {
        type: "block"
    },
    condition: {
        urlFilter: "||webkit.org",
        resourceTypes: [ "main_frame" ]
    }
}

8:41 - Modifying network requests

{
    "manifest_version": 3,
    "name": "Shiny OnTrack",
    "description": "Stay on track while you browse the web",
    "version": 1.0,

    "icons": {
        "512": "images/icon.svg"
    },

    "options_ui": {
        "page": "options.html"
    },
  
    "permissions": [ "declarativeNetRequest" ],

    "declarativeNetRequest": {
        "rule_resources": [
            {
                "id": "ruleset_id",
                "enabled": true,
                "path": "rules.json"
            }
        ]
    }
}

8:50 - Updating dynamic rules

await browser.declarativeNetRequest.updateDynamicRules({
    addRules: [ rule ]
})

9:19 - Wiring up the static declarativeNetRequest rules

{
    "manifest_version": 3,
    "name": "Shiny OnTrack",
    "description": "Stay on track while you browse the web",
    "version": 1.0,

    "icons": {
        "512": "images/icon.svg"
    },

    "options_ui": {
        "page": "options.html"
    },
  
    "permissions": [ 
      "declarativeNetRequest" 
    ]
}

9:40 - Adding block rules dynamically

// A helper function to map the host to the declarative net request rule ID.
export function hostToRuleID(host) {
	let hash = 0;
	for (let i = 0; i < host.length; i++) {
		hash = ((hash << 5) + hash) + host.charCodeAt(i);
		hash |= 0;
	}
	return Math.abs(hash) || 1;
}

function createBlockRule(host) {
	return {
		id: hostToRuleID(host),
		priority: 1,
		action: {
			type: "block"
		},
		condition: {
			urlFilter: `||${host}`,
			resourceTypes: ["main_frame"]
		}
	}
}

export async function createRules(hosts) {
	try {
		await browser.declarativeNetRequest.updateDynamicRules({
			addRules: hosts.map(createBlockRule)
		})
	} catch {
		console.log("Failed to create declarative net request rules")
	}
}

10:10 - Handling adding hosts to the settings

import { createRules, removeAllRules, removeRule } from './rules.js'

export async function addHost(host, blockingMode) {
  if (!host)
    return
  
  if (blockingMode === "full")
    await createRules([host])
}

10:48 - Redirecting network requests

{
    id: 1,
    priority: 1,
    action: {
        type: "redirect",
        redirect: {
            extensionPath: "/blocked.html"
        }
    },
    condition: {
        urlFilter: "||webkit.org",
        resourceTypes: [ "main_frame" ]
    }
}

11:17 - Declaring optional host permissions

{
    "manifest_version": 3,
    "name": "Shiny OnTrack",
    "description": "Stay on track while you browse the web",
    "version": 1.0,

    "icons": {
        "512": "images/icon.svg"
    },

    "options_ui": {
        "page": "options.html"
    },
  
    "permissions": [ "declarativeNetRequestWithHostAccess" ],
    "optional_host_permissions": [ "https://webkit.org/*" ]

}

11:54 - Declaring optional host permissions for all sites

{
    "manifest_version": 3,
    "name": "Shiny OnTrack",
    "description": "Stay on track while you browse the web",
    "version": 1.0,

    "icons": {
        "512": "images/icon.svg"
    },

    "options_ui": {
        "page": "options.html"
    },
  
    "permissions": [ "declarativeNetRequestWithHostAccess" ],
    "optional_host_permissions": [ "*://*/*" ]

}

13:12 - Add the redirect rule

// A helper function to map the host to the declarative net request rule ID.
export function hostToRuleID(host) {
	let hash = 0;
	for (let i = 0; i < host.length; i++) {
		hash = ((hash << 5) + hash) + host.charCodeAt(i);
		hash |= 0;
	}
	return Math.abs(hash) || 1;
}

function createBlockRule(host) {
	return {
		id: hostToRuleID(host),
		priority: 1,
		action: {
			type: "block"
		},
		condition: {
			urlFilter: `||${host}`,
			resourceTypes: ["main_frame"]
		}
	}
}

function createRedirectRule(host) {
	return {
		id: hostToRuleID(host),
		priority: 1,
		action: {
			type: "redirect",
			redirect: { extensionPath: "/blocked.html" }
		},
		condition: {
			urlFilter: `||${host}`,
			resourceTypes: ["main_frame"]
		}
	}
}

export async function createRules(hosts) {
	try {
		await browser.declarativeNetRequest.updateDynamicRules({
			addRules: hosts.map(createRedirectRule)
		})
	} catch {
		console.log("Failed to create declarative net request rules")
	}
}

13:42 - Dynamically ask for host permissions

import { createRules, removeAllRules, removeRule } from './rules.js'

export async function addHost(host, blockingMode) {
  if (!host)
    return
  
  const granted = await browser.permissions.request({
    origins: [`*://${host}/*`, `*://*.${host}/*`]
  })
  if (!granted)
    return
  
  if (blockingMode === "full")
    await createRules([host])
}

14:55 - Defining content scripts

{
    "manifest_version": 3,
    "name": "Shiny OnTrack",
    "description": "Stay on track while you browse the web",
    "version": 1.0,

    "icons": {
        "512": "images/icon.svg"
    },

    "options_ui": {
        "page": "options.html"
    },
  
    "permissions": [ "declarativeNetRequestWithHostAccess" ],
    "optional_host_permissions": [ "*://*/*" ],
  
    "content_scripts": [
        {
            "js": [ "content.js" ],
            "css": [ "content.css" ],
            "matches": [ "*://*.webkit.org/*" ]
        }
    ]
}

15:13 - Dynamically registering content scripts

let script = {
    id: "id",
    js: [ "content.js" ],
    css: [ "content.css" ],
    matches: [ "*://*.webkit.org/*" ],
    persistAcrossSessions: true
}

await browser.scripting.registerContentScripts([ script ])

15:31 - Adding the scripting permission

{
    "manifest_version": 3,
    "name": "Shiny OnTrack",
    "description": "Stay on track while you browse the web",
    "version": 1.0,
  
    "icons": {
        "512": "images/icon.svg"
    },
  
    "options_page": "options.html",
  
    "permissions": [
        "declarativeNetRequestWithHostAccess",
        "scripting"
    ],
  
    "optional_host_permissions": [ "*://*/*" ]
}

15:41 - Registering content scripts

// scripting.js

function contentScript(host) {
    return {
        id: `cs-${host}`,
        js: [ "content.js" ],
        css: [ "content.css" ],
        matches: [ `*://${host}/*`, `*://*.${host}/*` ],
        persistAcrossSessions: true
    }
}

export function registerScripts(hosts) {
    const scripts = hosts.map(contentScript)
    try {
        await browser.scripting.registerContentScripts(scripts)
    } catch {
        console.log("Failed to register content scripts")
    }
}

16:02 - Adding a host

// host.js

export async function addHost(host, blockMode) {
    if (!host)
        return

    const granted = await browser.permissions.request({
        origins: [`*://${host}/*`, `*://*.${host}/*`]
    })

    if (!granted)
        return

    if (blockingMode === "full")
        await createRules([ host ])

    await registerScripts([ host ])
}

17:06 - Web extensions storage APIs

await browser.session.storage.set({
  key: value
})

await browser.local.storage.set({
  key: value
})

17:21 - Adding storage permission to the web extension manifest.json

{
    "manifest_version": 3,
    "name": "Shiny OnTrack",
    "description": "Stay on track while you browse the web",
    "version": 1.0,
  
    "icons": {
        "512": "images/icon.svg"
    },
  
    "options_page": "options.html",
  
    "permissions": [
        "declarativeNetRequestWithHostAccess",
        "scripting",
        "storage"
    ],
  
    "optional_host_permissions": [ "*://*/*" ]
}

17:30 - Saving data with storage

// storage.js

export async function updateHosts(hosts) {
    await browser.storage.local.set({ hosts: hosts })
}

export async function getHosts() {
    const { hosts = [] } = await browser.storage.local.get("hosts")
    return hosts
}

export async function saveBlockMode(mode) {
    await browser.storage.local.set({ blockMode: mode })
}

export async function getBlockMode() {
    const { blockMode = "full" } = await browser.storage.local.get("blockMode")
    return blockMode
}

17:41 - Persisting hosts to storage

// host.js

export async function addHost(host, blockMode) {
    if (!host)
        return

    const granted = await browser.permissions.request({
        origins: [`*://${host}/*`, `*://*.${host}/*`]
    })

    if (!granted)
        return

    if (blockingMode === "full")
        await createRules([ host ])

    await registerScripts([ host ])

    let existingHosts = await getHosts()
    let updatedHosts = [ ...existingHosts, host ]
    await updateHosts(updatedHosts)
}

17:51 - Reading from storage

// options.js

let existingHosts = await getHosts()
let blockMode = await getBlockMode()

displayBlocklist(existingHosts)

18:00 - Switching block modes

// host.js

export async function userDidSwitchMode(blockMode) {
    await saveBlockMode(blockMode)

    if (blockMode === "full") {
        let hosts = await getHosts()
        await createRules(hosts)
    } else
        await removeAllRules()
}

19:01 - Adding a background script

{
    "manifest_version": 3,
    "name": "Shiny OnTrack",
    "description": "Stay on track while you browse the web",
    "version": 1.0,
  
    "icons": {
        "512": "images/icon.svg"
    },
  
    "options_page": "options.html",
  
    "permissions": [
        "declarativeNetRequestWithHostAccess",
        "scripting",
        "storage"
    ],
  
    "optional_host_permissions": [ "*://*/*" ],
  
    "background": {
        "scripts": [ "background.js" ],
        "type": "module"
    }
}

19:39 - Background script

// background.js

import { registerScripts } from "./utilities/scripting.js"
import { getHosts } from "./utilities/storage.js"

browser.runtime.onInstalled.addListener(async (details) => {
    if (details.reason !== "update")
        return

    const hosts = await getHosts()
    await registerScripts(hosts)
})

22:49 - Package your web extension into an app for Xcode

xcrun safari-web-extension-packager --copy-resources /path/to/ShinyOnTrack

23:32 - Adding the nativeMessaging permission

{
    "manifest_version": 3,
    "name": "Shiny OnTrack",
    "description": "Stay on track while you browse the web",
    "version": 1.0,
  
    "icons": {
        "512": "images/icon.svg"
    },
  
    "options_page": "options.html",
  
    "permissions": [
        "declarativeNetRequestWithHostAccess",
        "scripting",
        "storage",
        "nativeMessaging"
    ],
  
    "optional_host_permissions": [ "*://*/*" ],
  
    "background": {
        "scripts": [ "background.js" ],
        "type": "module"
    }
}

23:40 - Sending a native message

// background.js

import { registerScripts } from "./utilities/scripting.js"
import { getHosts } from "./utilities/storage.js"

browser.runtime.onInstalled.addListener(async (details) => {
    if (details.reason !== "update")
        return

    const hosts = await getHosts()
    await registerScripts(hosts)
})

export async function requestBioAuth() {
    const message = { message: "requestBioAuth" }
    const response = await browser.runtime.sendNativeMessage(message)
    return response?.success
}

23:55 - Handling native messages

// SafariWebExtensionHandler.swift

import LocalAuthentication

class SafariWebExtensionHandler: NSObject, NSExtensionRequestHandling {
    func beginRequest(with context: NSExtensionContext) {
        let request = context.inputItems.first as? NSExtensionItem
        let message = request?.userInfo?[SFExtensionMessageKey] as? [String: Any]

        if message?["message"] as? String == "requestBioAuth" {
            let lAContext = LAContext()
            Task {
                do {
                    let success = try await lAContext.evaluatePolicy(
                        .deviceOwnerAuthenticationWithBiometrics,
                        localizedReason: "Authenticate to change blocked sites"
                    )
                    self.reply(context: context, success: success)
                } catch {
                    self.reply(context: context, success: false)
                }
            }
        }
    }
}

24:25 - Replying to a native message

// SafariWebExtensionHandler.swift

import LocalAuthentication

class SafariWebExtensionHandler: NSObject, NSExtensionRequestHandling {
    func beginRequest(with context: NSExtensionContext) {
        let request = context.inputItems.first as? NSExtensionItem
        let message = request?.userInfo?[SFExtensionMessageKey] as? [String: Any]

        if message?["message"] as? String == "requestBioAuth" {
            let lAContext = LAContext()
            Task {
                do {
                    let success = try await lAContext.evaluatePolicy(
                        .deviceOwnerAuthenticationWithBiometrics,
                        localizedReason: "Authenticate to change blocked sites"
                    )
                    self.reply(context: context, success: success)
                } catch {
                    self.reply(context: context, success: false)
                }
            }
        }
    }

    private func reply(context: NSExtensionContext, success: Bool) {
        let response = NSExtensionItem()
        response.userInfo = [SFExtensionMessageKey: ["success": success]]
        context.completeRequest(returningItems: [response], completionHandler: nil)
    }
}

- 0:00 - Introduction
- Learn how Safari web extensions — built with HTML, CSS, and JavaScript and packaged inside an app — can run across iOS, iPadOS, macOS, and visionOS. Preview the distraction-blocker extension built throughout the session, which offers a 10-minute light mode and a full redirect mode.
- 3:23 - Get started
- Set up an extension from scratch by writing a manifest.json file, then add a popup UI so the extension is reachable from Safari's toolbar. The same project runs unchanged across every Apple platform that ships Safari.
- 7:23 - Block content
- Use the declarativeNetRequest API to block, modify, and redirect network requests, and declare the host permissions — including optional host permissions — that let users grant access on the sites where the extension should run.
- 14:40 - Modify webpages
- Inject content into pages with content scripts to render a countdown timer on distracting sites. Register scripts dynamically with the scripting API and persist user preferences and per-host state using the storage API and a background service worker.
- 19:53 - Package and distribute
- Submit a Safari web extension to the App Store using App Store Connect, and share beta builds with testers through TestFlight.
- 22:33 - Communicate with your app
- Generate an Xcode project with the Safari Web Extension Packager, then use native messaging to pass requests between the JavaScript extension and its containing app — unlocking platform features like Local Authentication that aren't available to web APIs.
- 26:04 - Next steps
- Download the sample project, explore the cross-browser WebExtensions documentation on MDN, and file feedback through Feedback Assistant or bugs.webkit.org.

探索“入门汇总”

及时了解最新动态

探索“平台”

精选

探索“技术”

精选

探索“社区”

精选

探索“文档”

发布说明

探索“下载”

精选

探索“支持”

精选

快速链接

章节

资源

相关视频

WWDC26