与其他问题无关的更新
这是三个部分的第一部分,介绍对不属于扩展 Service Worker 的代码进行所需的更改。本部分将介绍与其他问题无关的必要代码更改。接下来的两部分将介绍如何替换阻止网络请求和提高安全性。
将 tabs.executeScript()替换为 scripting.executeScript()
在 Manifest V3 中,executeScript()
从 tabs
API 移至 scripting
API。这要求除了实际的代码更改之外,还需要对清单文件中的权限进行更改。
对于 executeScript()
方法,您需要:
"scripting"
权限。- 主机权限或
"activeTab"
权限。
scripting.executeScript()
方法与其使用 tabs.executeScript()
的方式类似。两者之间有少许差异。
- 旧方法只能接受单个文件,而新方法可以接受一组文件。
- 您还要传递
ScriptInjection
对象,而不是InjectDetails
。两者之间有很多区别。例如,tabId
现在作为ScriptInjection.target
的成员(而不是方法参数)传递。
以下示例展示了如何执行此操作。
async function getCurrentTab() {/* ... */} let tab = await getCurrentTab(); chrome.tabs.executeScript( tab.id, { file: 'content-script.js' } );
async function getCurrentTab() let tab = await getCurrentTab(); chrome.scripting.executeScript({ target: {tabId: tab.id}, files: ['content-script.js'] });
将 tab.insertCSS() 和 tab.removeCSS() 替换为 scripting.insertCSS() 和 scripting.removeCSS()
在 Manifest V3 中,insertCSS()
和 removeCSS()
从 tabs
API 移至 scripting
API。这不仅需要更改代码,还需要对清单文件中的权限进行更改:
"scripting"
权限。- 主机权限或
"activeTab"
权限。
scripting
API 上的函数与 tabs
上的函数类似。两者之间有少许差异。
- 调用这些方法时,您将传递
CSSInjection
对象,而不是InjectDetails
。 tabId
现在作为CSSInjection.target
的成员(而不是作为方法参数)进行传递。
以下示例展示了如何针对 insertCSS()
执行此操作。removeCSS()
的过程相同。
chrome.tabs.insertCSS(tabId, injectDetails, () => { // callback code });
const insertPromise = await chrome.scripting.insertCSS({ files: ["style.css"], target: { tabId: tab.id } }); // Remaining code.
将浏览器操作和网页操作替换为操作
浏览器操作和页面操作是 Manifest V2 中的两个独立概念。虽然一开始它们扮演了不同的角色,但随着时间推移,它们之间的差异逐渐缩小了。在 Manifest V3 中,这些概念已整合到 Action API 中。这就需要您对 manifest.json
和扩展代码进行更改,且更改的内容不同于您在 Manifest V2 后台脚本中放置的内容。
Manifest V3 中的 Action 与浏览器操作最为相似;不过,action
API 并不像 pageAction
那样提供 hide()
和 show()
。如果您仍需要网页操作,可以使用声明式内容模拟这些操作,也可以使用标签页 ID 调用 enable()
或 disable()
。
将“browser_action”和“page_action”替换为“action”
在 manifest.json
中,将 "browser_action"
和 "page_action"
字段替换为 "action"
字段。如需了解 "action"
字段的相关信息,请参阅参考文档。
{ ... "page_action": { ... }, "browser_action": { "default_popup": "popup.html" } ... }
{ ... "action": { "default_popup": "popup.html" } ... }
将 browserAction API 和 pageAction API 替换为操作 API
如果您的 Manifest V2 使用 browserAction
和 pageAction
API,现在应使用 action
API。
chrome.browserAction.onClicked.addListener(tab => { ... }); chrome.pageAction.onClicked.addListener(tab => { ... });
chrome.action.onClicked.addListener(tab => { ... });
将回调替换为 promise
在 Manifest V3 中,许多扩展 API 方法都会返回 promise。Promise 是异步方法返回的值的代理或占位符。如果您从未使用过 Promise,可以在 MDN 上了解相关信息。本页介绍了在 Chrome 扩展程序中使用这些扩展程序的须知事项。
为了实现向后兼容性,许多方法在添加 promise 支持后会继续支持回调。请注意,您不能在同一个函数调用中同时使用这两者。如果您传递回调,函数将不会返回 promise;如果希望返回 promise,则也不传递回调。某些 API 功能(例如事件监听器)将继续需要回调。如需检查某个方法是否支持 promise,请在其 API 参考文档中查找“Promise”标签。
如需从回调转换为 promise,请移除回调并处理返回的 promise。以下示例取自可选权限示例,具体而言是 newtab.js
。回调版本显示了示例使用回调调用 request()
时的效果。请注意,promise 版本可以用 async 和 await 重写。
chrome.permissions.request(newPerms, (granted) => { if (granted) { console.log('granted'); } else { console.log('not granted'); } });
const newPerms = { permissions: ['topSites'] }; chrome.permissions.request(newPerms) .then((granted) => { if (granted) { console.log('granted'); } else { console.log('not granted'); } });
替换需要 Manifest V2 后台上下文的函数
其他扩展程序上下文只能使用消息传递与扩展程序 Service Worker 交互。因此,您需要替换需要后台上下文的调用,具体来说:
chrome.runtime.getBackgroundPage()
chrome.extension.getBackgroundPage()
chrome.extension.getExtensionTabs()
您的扩展程序脚本应使用消息传递在 Service Worker 与扩展程序的其他部分之间进行通信。目前,这需要在扩展 Service Worker 中使用 sendMessage()
并实现 chrome.runtime.onMessage
。从长远来看,您应该计划将这些调用替换为 postMessage()
和 Service Worker 的消息事件处理脚本。
替换不受支持的 API
下列方法和属性需要在 Manifest V3 中更改。
Manifest V2 方法或属性 | 替换为 |
---|---|
chrome.extension.connect() |
chrome.runtime.connect() |
chrome.extension.connectNative() |
chrome.runtime.connectNative() |
chrome.extension.getExtensionTabs() |
chrome.extension.getViews() |
chrome.extension.getURL() |
chrome.runtime.getURL() |
chrome.extension.lastError |
如果方法返回 promise,请使用 promise.catch() |
chrome.extension.onConnect |
chrome.runtime.onConnect |
chrome.extension.onConnectExternal |
chrome.runtime.onConnectExternal |
chrome.extension.onMessage |
chrome.runtime.onMessage |
chrome.extension.onRequest |
chrome.runtime.onMessage |
chrome.extension.onRequestExternal |
chrome.runtime.onMessageExternal |
chrome.extension.sendMessage() |
chrome.runtime.sendMessage() |
chrome.extension.sendNativeMessage() |
chrome.runtime.sendNativeMessage() |
chrome.extension.sendRequest() |
chrome.runtime.sendMessage() |
chrome.runtime.onSuspend (后台脚本) |
在扩展 Service Worker 中不受支持。请改用 beforeunload 文档事件。 |
chrome.tabs.getAllInWindow() |
chrome.tabs.query() |
chrome.tabs.getSelected() |
chrome.tabs.query() |
chrome.tabs.onActiveChanged |
chrome.tabs.onActivated |
chrome.tabs.onHighlightChanged |
chrome.tabs.onHighlighted |
chrome.tabs.onSelectionChanged |
chrome.tabs.onActivated |
chrome.tabs.sendRequest() |
chrome.runtime.sendMessage() |
chrome.tabs.Tab.selected |
chrome.tabs.Tab.highlighted |