浏览器插件开发-常用API

浏览器插件开发-常用API

调研资料

💥 当前文档基于 manifest v2, 最新版的 manifest v3 有很大不同，建议直接查看官方文档–2022.03.08

• manifest.json 官方文档
• Chrome Extension API
• 360浏览器的插件文档 中文, 虽然内核差不多但是不一定与 Chrome api 一致, 可以作为参考
• Chrome 官方案例库
• 案例
• 如何实现网页和Chrome插件之间的通信
• 消息传递
• Safari 浏览器插件（扩展）开发
• 关于浏览器插件开发过程中注入脚本与页面内容间的通信

常用 API

1. chrome.runtime

管理 background 返回关于清单的详细信息，并侦听和响应应用程序或扩展生命周期中的事件。您还可以使用这个API将url的相对路径转换为完全限定的url。

1. chrome.runtime.getBackgroundPage(background: Window => {...}) 返回当前扩展的 background 对象
2. chrome.runtime.ma 返回清单文件
3. chrome.runtime.getURL 返回扩展中文件相对于安装位置的路径
4. chrome.runtime.setUninstallURL 设置卸载时要访问的 URL
5. chrome.runtime.reload 重新加载扩展

2. chrome.cookies

使用前需要先注册权限

{
    "permission": [
        "cookies",
        "https://*.xxx.com"
    ]
}

常规方法 get | remove | set | getAll 等除外，以下是可能会用到的 api

1. chrome.cookies.onChanged.addListener(({removed, cookie}) => {...}) removed=true 表示的是cookie被删除的情况，否则表示被添加或者设置，cookie 表示操作的cookie

3. chrome.tabs

浏览器标签操作，需要开通标签操作的权限

{
    "permission": [
        "tabs",
        "https://*.xxx.com"
    ]
}

1. chrome.tabs.create(params, callback) 创建一个新的标签，以下是 params 参数
   • windowId 创建新标签的目标窗口，默认当前窗口
   • index 标签在窗口中的位置
   • url 标签导航的初始页面
   • selected 是否为选中的 默认是true
   • pinned 标签是否为固定
   • callback(tab) tab 是创建后的标签的细节，包括id
2. chrome.tabs.executeScript(tabId, details, callback) 向标签页注入脚本
   • tabId 标签页ID，默认为当前选中窗口
   • details.code 直接注入的脚本代码
   • details.file 也可以指定注入的脚本文件，与 details.code 二选一
3. chrome.tabs.get(tabId, callback) 获取指定标签页的细节
4. chrome.tabs.getSelected(windowId, callback) 获取特定窗口（windowId 默认为当前窗口） 的选中的标签
5. chrome.tabs.insertCSS(tabId, details, callback) 向页面注入样式
6. chrome.tabs.remove(tabId, callback) 移除标签
7. 其他信息参照文档

4. chrome.extension

主要被用于通信支持，提供 扩展与 content_script 之间， 扩展与扩展之间，与大多数 chrome.* API 不同，chrome.extension 部分功能可以直接在 content_script 中使用

注意 chrome.extension 与 chrome.runtime 由很多重叠的 api , chrome.extension 比较老旧，尽量使用 chrome.runtime

1. chrome.extension.connect(extensionId, connectInfo) 尝试连接到扩展内的其他监听者，主要用于 content_script => 扩展进程 的连接，由扩展进程 => content_script 的主动连接则可通过 chrome.tabs.connect() 连接
   • extensionId 想要连接的扩展的扩展ID, 默认为注入这个 content_script 的扩展
2. chrome.extension.onConnect.addListener(listener) 监听到发来的连接时触发的监听函数
3. chrome.extension.sendMessage(extensionId, message, responseCallback) 向扩展内的其他监听者发送消息
   • extensionId 扩展Id, 默认为函数调用者所在的扩展
   • message
   • responseCallback(response) 返回的响应数据
4. chrome.extension.onMessage.addListener(details => {...}) 接收到本扩展中消息后的监听函数
   • details.message 信息
   • details.sender 信息发送者
   • details.sendRender() 发送响应消息，只能调用一次
5. chrome.extension.getURL(path) 将扩展内的文件路径转换为 普通页面可用的文件路径
6. chrome.extension.getBackgroundPage() 返回扩展中当前运行的 background 页面
7. chrome.extension.getViews(fetchProperties) 返回指定类型的页面，包括标签页、后台页、弹窗页等
   • fetchProperties.type 可以是 [“tabs”, “popup”, “infobar”, “notification”] 省略这项会返回所有吧类型的页面 包括 background

注意，只有以下 extension API 可以在 content_script 中使用

1. chrome.extension.connect
2. chrome.extension.onConnect
3. chrome.extension.sendMessage
4. chrome.extension.onMessage
5. chrome.extension.getURL

5. chrome.webNavigation

处理正在进行中的导航请求，需要开通权限

{
    "permission": [
        "webNavigation",
    ]
}

一个普通的导航从开始到导航结束所经历的生命周期如下

onBeforeNavigate => onCommitted => onDOMContentLoaded => onCompleted

1. transitionType 各个监听事件中都会返回的一个类型值，表示当前导航的触发原因
   • 可以包含的值：["link", "typed", "auto_bookmark", "reload", ...] 多数情况下用来指引，新打开的标签页是怎么触发的
2. chrome.webNavigation.onBeforeNavigate.addListener(details => {...}) 导航即将发生时触发
   • details.tabId 导航即将打开的 tab 的 id
   • details.url 即将打开的 url
   • details…
3. chrome.webNavigation.onCommitted.addListener(details => {...}) 导航提交时触发，在这个时候，document 仍然在下载，它所引用的资源也可能在下载，但是浏览器已经接受少部分文档，并决定切换到新的文档
   • details.tabId 导航即将打开的 tab 的 id
   • details.url 即将打开的 url
   • details.transitionType 导航的原因
4. chrome.webNavigation.onDOMContentLoaded.addListener(details => {...}) 在页面 DOM 构造完成时触发，但是DOM所引用的资源不一定加载完成
   • details.tabId 导航即将打开的 tab 的 id
   • details.url 即将打开的 url
5. chrome.webNavigation.onCompleted.addListener(details => {...}) DOM 及其引用的资源全部加载完成时触发
   • details.tabId 发生导航的 tab 的 id
   • details.url 发生导航的 url

6. chrome.storage

用户数据的存储、检索、跟踪，与localStorage 相比做了很多的优化，使用时需要获取权限

{
    "permissions": [
      "storage"
    ]
}

关键点

1. content_script 中可以直接访问
2. 可以是异步的，可以批量读写
3. 可以存储对象，而不像 localStorage 只能存字符串
4. 可以同步到 Chrome 账户，需要使用 storage.sync

storage.sync 与 storage.local 都用来存储数据 只不过 storage.sync 可以同步到 Chrome 账户，以下以 storage.local 为例

1. chrome.storage.onChanged.addListener((changes, namespace) => {...}) 监听存储事件
   • changes[key].newValue 更新后的值
   • changes[key].oldValue 更新前的值
2. chrome.storage.local.get(key|keyArray, callback) 读取存储 key 可以是字符春或者数组，数组代表获取多个 key 对应的存储，key=null 获取所有存储 callback 中可以得到获取的值，必填
3. chrome.storage.local.set(Object, callback) 设置或者耿勋存储，会触发 onChanged 事件
4. chrome.storage.local.remove('name', callback) 移除某一个存储
5. chrome.storage.local.clear(callback) 清除所有存储