browserAction.setIcon()

这是一个设置浏览器操作图标的函数。

你可以指定单个图标，可以是图像文件的路径，也可以是一个 browserAction.ImageDataType 对象。

如果要指定多个不同尺寸的图标，可以提供一个包含多个路径或 ImageData 对象的字典。这意味着图标不需要为具有不同像素密度的设备进行缩放。

如果没有指定特定图标的标签，将会继承全局图标，其默认为清单中指定的 default_icon。

这是一个返回 Promise 的异步函数。

语法

js
let settingIcon = browser.browserAction.setIcon(
  details         // object
)

参数

details

object。一个包含 imageData 或 path 属性的对象，可选地包含一个 tabId 属性。

imageData 可选

browserAction.ImageDataType 或 object。这可以是单个 ImageData 对象或一个字典对象。

使用字典对象来指定不同尺寸的多个 ImageData 对象，这样图标就不需要根据设备的不同像素密度进行缩放。如果 ImageData 是一个字典，则每个属性的值是一个 ImageData 对象，属性名是其尺寸，如下所示：

js
let settingIcon = browser.action.setIcon({
  imageData: {
    16: image16,
    32: image32,
  },
});

浏览器将根据屏幕的像素密度选择要使用的图像。有关更多信息，请参阅选择图标大小。

path 可选

string 或 object。这可以是到图标文件的相对路径，也可以是一个字典对象。

使用字典对象来指定不同尺寸的多个图标文件，这样图标就不需要根据设备的不同像素密度进行缩放。如果 path 是一个字典，则每个属性的值是一个相对路径，属性名是其尺寸，如下所示：

js
let settingIcon = browser.action.setIcon({
  path: {
    16: "path/to/image16.jpg",
    32: "path/to/image32.jpg",
  },
});

浏览器将根据屏幕的像素密度选择要使用的图像。有关更多信息，请参阅选择图标大小。

tabId 可选

integer。仅为给定的标签设置图标。用户将该标签导航到新页面时，图标将被重置。

windowId 可选

integer。为给定的窗口设置图标。

  • 如果同时提供了 windowId 和 tabId，函数将失败，并且图标不会设置。
  • 如果同时省略了 windowId 和 tabId，则设置全局图标。

如果 imageData 和 path 中的每一个都是 undefined、null 或空对象中的一种：

  • 如果指定了 tabId，并且标签设置了其特定标签图标，则该标签将从其所属的窗口继承图标。
  • 如果指定了 windowId，并且窗口设置了其特定的窗口图标，则该窗口将继承全局图标。
  • 否则，全局图标将重置为清单中的图标。

返回值

一个 Promise，一旦图标设置完成，其会兑现且不带任何参数。

浏览器兼容性

BCD tables only load in the browser

示例

以下示例代码使用浏览器操作来切换对 webRequest.onHeadersReceived 的监听器，并使用 setIcon() 来指示监听器是开启还是关闭：

js
function logResponseHeaders(requestDetails) {
  console.log(requestDetails);
}

function startListening() {
  browser.webRequest.onHeadersReceived.addListener(
    logResponseHeaders,
    { urls: ["<all_urls>"] },
    ["responseHeaders"],
  );
  browser.browserAction.setIcon({ path: "icons/listening-on.svg" });
}

function stopListening() {
  browser.webRequest.onHeadersReceived.removeListener(logResponseHeaders);
  browser.browserAction.setIcon({ path: "icons/listening-off.svg" });
}

function toggleListener() {
  if (browser.webRequest.onHeadersReceived.hasListener(logResponseHeaders)) {
    stopListening();
  } else {
    startListening();
  }
}

browser.browserAction.onClicked.addListener(toggleListener);

以下代码使用 ImageData 对象设置图标：

js
function getImageData() {
  let canvas = document.createElement("canvas");
  let ctx = canvas.getContext("2d");

  ctx.fillStyle = "green";
  ctx.fillRect(10, 10, 100, 100);

  return ctx.getImageData(50, 50, 100, 100);
}

browser.browserAction.onClicked.addListener(() => {
  browser.browserAction.setIcon({ imageData: getImageData() });
});

以下代码段在用户点击图标时更新图标，但仅适用于活动选项卡：

js
browser.browserAction.onClicked.addListener((tab) => {
  browser.browserAction.setIcon({
    tabId: tab.id,
    path: "icons/updated-48.png",
  });
});

示例扩展

备注： 此 API 基于 Chromium 的 chrome.browserAction API。该文档衍生自 Chromium 代码中的 browser_action.json。