browserAction.setIcon()

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

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

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

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

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

语法

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

参数

details

object。一个包含 imageDatapath 属性的对象,可选地包含一个 tabId 属性。

imageData 可选

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

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

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

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

path 可选

stringobject。这可以是到图标文件的相对路径,也可以是一个字典对象。

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

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

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

tabId 可选

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

windowId 可选

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

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

如果 imageDatapath 中的每一个都是 undefinednull 或空对象中的一种:

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

返回值

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

浏览器兼容性

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Firefox for Android
Safari on iOS
setIcon
details.imageData parameter
details.windowId parameter
The path and imageData properties of the details parameter can be set to null.

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
See implementation notes.
Has more compatibility info.

示例

以下示例代码使用浏览器操作来切换对 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