更新代码

与其他问题无关的更新

这是三部分的第一部分，介绍对不属于扩展 Service Worker 的代码进行哪些更改。此部分介绍需要进行的代码更改，并且这些更改与其他问题无关。接下来的两部分将介绍如何替换屏蔽 Web 请求和提高安全性。

将 tab.executeScript()替换为 scripting.executeScript()

在 Manifest V3 中，executeScript() 从 tabs API 移至 scripting API。这就需要在实际的代码更改的基础上更改清单文件中的权限。

对于 executeScript() 方法，您需要：

  • "scripting" 权限。
  • 主机权限或 "activeTab" 权限。

scripting.executeScript() 方法与其使用 tabs.executeScript() 的方式类似。但还是有一些区别。

  • 旧方法只能接受一个文件，而新方法可以接受一组文件。
  • 您还将传递 ScriptInjection 对象，而不是 InjectDetails。两者之间有多种不同。例如，tabId 现在作为 ScriptInjection.target 的成员（而不是方法参数）传递。

以下示例展示了如何执行此操作。

Manifest V2
async function getCurrentTab() {/* ... */}
let tab = await getCurrentTab();

chrome.tabs.executeScript(
  tab.id,
  {
    file: 'content-script.js'
  }
);

位于后台脚本文件中。

Manifest V3
async function getCurrentTab()
let tab = await getCurrentTab();

chrome.scripting.executeScript({
  target: {tabId: tab.id},
  files: ['content-script.js']
});

在扩展 Service Worker 中。

将 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() 的过程相同。

Manifest V2
chrome.tabs.insertCSS(tabId, injectDetails, () => {
  // callback code
});

位于后台脚本文件中。

Manifest V3
const insertPromise = await chrome.scripting.insertCSS({
  files: ["style.css"],
  target: { tabId: tab.id }
});
// Remaining code.

在扩展 Service Worker 中。

将浏览器操作和网页操作替换为操作

在 Manifest V2 中，浏览器操作和网页操作是两个单独的概念。虽然一开始他们扮演的角色不同，但随着时间的推移，它们之间的差异越来越小。在 Manifest V3 中，这些概念已整合到 Action API 中。这需要更改 manifest.json 和扩展代码，且不得在 Manifest V2 后台脚本中更改。

Manifest V3 中的操作与浏览器操作最为相似；不过，action API 不像 pageAction 那样提供 hide() 和 show()。如果您仍需要页面操作，可以使用声明性内容模拟这些操作，也可以使用标签页 ID 调用 enable() 或 disable()。

将“browser_action”和“page_action”替换为“action”

在 manifest.json 中，将 "browser_action" 和 "page_action" 字段替换为 "action" 字段。如需了解 "action" 字段的相关信息，请参阅参考文档。

Manifest V2
{
  ...
  "page_action": { ... },
  "browser_action": {
    "default_popup": "popup.html"
   }
  ...
}
Manifest V3
{
  ...
  "action": {
    "default_popup": "popup.html"
  }

  ...
}

将 BrowserAction API 和 pageAction API 替换为 Action API

如果您的 Manifest V2 使用 browserAction 和 pageAction API，现在您应使用 action API。

Manifest V2
chrome.browserAction.onClicked.addListener(tab => { ... });
chrome.pageAction.onClicked.addListener(tab => { ... });
Manifest V3
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() 会是什么样子。请注意，可以用 async 和 await 重写 promise 版本。

回调
chrome.permissions.request(newPerms, (granted) => {
  if (granted) {
    console.log('granted');
  } else {
    console.log('not granted');
  }
});
Promise
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 和扩展程序的其他部分之间进行通信。目前，这需要使用 sendMessage()，并在扩展 Service Worker 中实现 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.onRequest
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