action.setIcon()

设置浏览器操作的图标。

备注:该 API 在 Manifest V3 或更高版本中可用。

你可以指定图片文件的路径或 action.ImageDataType 对象作为单个图标。

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

没有特定图标的标签页将继承全局图标,其默认为清单中指定的 default_icon

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

语法

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

参数

details

object,包含 imageDatapath 属性其一的对象,并且可选的包含 tabIdwindowId 属性。

imageData 可选

action.ImageDataTypeobject,这要么是 ImageData 对象,要么是一个字典对象。

使用一个字典对象来指定不同尺寸的多个 ImageData 对象,这样图标就不需要为具有不同像素密度的设备进行缩放。如果 imageData 是一个字典,那么每个属性的名称是其尺寸,值是 ImageData 对象,如下所示:

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

浏览器会根据屏幕的像素密度选择要使用的图像。有关更多信息,请参见选择图标尺寸

path 可选

stringobject,这要么是一个图标文件的相对路径,要么是一个字典对象。

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

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

浏览器会根据屏幕的像素密度选择要使用的图像。有关更多信息,请参见选择图标尺寸

tabId 可选

integer,指定要设置图标的标签页。当用户导航到新页面时,图标会被重置。

windowId 可选

integer,指定要设置图标的窗口。

  • 若同时指定了 windowIdtabId,则函数出错且不会设置图标。
  • 若同时未指定 windowIdtabId,则将设置全局图标。

imageDatapath 都是 undefinednull 或空对象其一,则:

  • 若指定了 tabId,且标签页设置了一个指定的图标,则标签页会继承它对应的窗口的图标。
  • 若指定了 windowId,且窗口设置了一个指定的图标,则窗口会继承全局图标。
  • 否则,全局图标会被重置为清单中的图标。

返回值

当图标被设置时,返回不兑现任何参数的 Promise

示例

这段代码使用浏览器操作来切换监听器的状态,监听器使用 webRequest.onHeadersReceived,并使用 setIcon() 来指示监听器是开启还是关闭的:

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

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

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

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

browser.action.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.action.onClicked.addListener(() => {
  browser.action.setIcon({ imageData: getImageData() });
});

下面的代码在用户点击图标时更新图标,但仅对活动标签页生效:

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

浏览器兼容性

BCD tables only load in the browser

备注:该 API 基于 Chromium 的 chrome.action API。本文衍生自 Chromium 代码中的 browser_action.json