浏览器插件开发-常用API

调研资料

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

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

使用前需要先注册权限

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

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

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

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

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

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

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

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

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

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

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

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

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

onBeforeNavigate => onCommitted => onDOMContentLoaded => onCompleted

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

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

{
    "permissions": [
      "storage"
    ]
}

关键点

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

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