action.setIcon()
设置浏览器操作的图标。
备注:该 API 在 Manifest V3 或更高版本中可用。
你可以指定图片文件的路径或 action.ImageDataType
对象作为单个图标。
你可以通过提供包含多个路径或 ImageData
对象的字典来指定不同尺寸的多个图标。这意味着图标不需要为具有不同像素密度的设备进行缩放。
没有特定图标的标签页将继承全局图标,其默认为清单中指定的 default_icon
。
这是一个返回 Promise
的异步函数。
语法
let settingIcon = browser.action.setIcon(
details // object
)
参数
details
-
object
,包含imageData
、path
属性其一的对象,并且可选的包含tabId
、windowId
属性。imageData
可选-
或action.ImageDataType
object
,这要么是ImageData
对象,要么是一个字典对象。使用一个字典对象来指定不同尺寸的多个
ImageData
对象,这样图标就不需要为具有不同像素密度的设备进行缩放。如果imageData
是一个字典,那么每个属性的名称是其尺寸,值是ImageData
对象,如下所示:jslet settingIcon = browser.action.setIcon({ imageData: { 16: image16, 32: image32, }, });
浏览器会根据屏幕的像素密度选择要使用的图像。有关更多信息,请参见选择图标尺寸。
path
可选-
string
或object
,这要么是一个图标文件的相对路径,要么是一个字典对象。使用一个字典对象来指定不同尺寸的多个图标文件,这样图标就不需要为具有不同像素密度的设备进行缩放。如果
path
是一个字典,那么每个属性的名称是其尺寸,值是相对路径,如下所示:jslet 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
。
示例
这段代码使用浏览器操作来切换监听器的状态,监听器使用 webRequest.onHeadersReceived
,并使用 setIcon()
来指示监听器是开启还是关闭的:
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
对象设置图标:
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() });
});
下面的代码在用户点击图标时更新图标,但仅对活动标签页生效:
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
。