sidebarAction.setIcon()

设置侧边栏的图标。

你可以通过提供一个图片文件的路径,或一个 sidebarAction.ImageDataType 对象来指定单独一个图标。

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

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

图标类型

你的扩展应该在 sidebar_action 清单键中指定侧边栏的图标。这被称为“清单图标”。

如果你没有在 sidebar_action 键中指定图标,你将得到浏览器的默认图标。这被称为“默认图标”。

如果你使用 setIcon() 设置一个新图标,并包含 tabId 选项,那么将仅为指定的标签页设置图标。这个图标称为“标签页特定图标”。

如果你使用 setIcon() 设置一个新图标,并包含 windowId 选项,那么将仅为给定的窗口设置图标。这个图标称为“窗口特定图标”,并将出现在该窗口的所有没有设置标签页特定图标的标签页中。

如果你使用 setIcon() 设置一个新图标,并省略 tabIdwindowId 选项,那么这将设置“全局图标”。全局图标将出现在所有没有设置标签页特定图标的标签页中,且其窗口没有设置窗口特定图标的标签页中。

语法

js
let settingIcon = browser.sidebarAction.setIcon(
  details         // 对象
)

参数

details

object。包含如下属性的对象:

imageData 可选

sidebarAction.ImageDataTypeobject。这要么是一个单一的 ImageData 对象,要么是一个字典对象。

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

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

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

path 可选

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

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

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

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

如果 path 是一个空字符串,浏览器将使用默认图标。

如果 path 不为空但不指向图标文件,那么图标将被隐藏。

如果 pathnull,并且指定了 tabId,并且指定的标签页设置了标签页特定图标:那么如果设置了全局图标,该标签页的特定图标将重置为全局图标,否则将被重置为清单图标。

如果 pathnull,并且省略了 tabId,并且设置了全局图标,那么它将被重置为清单图标。

tabId 可选

integer。仅为指定的标签页设置图标。

windowId 可选

integer。仅为指定的窗口设置图标。

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

返回值

Promise,当图标被设置时将会不带任何参数地兑现。

浏览器兼容性

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Firefox for Android
Safari on iOS
setIcon
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

示例

下面的代码在用户点击浏览器操作时切换活动标签页的侧边栏图标:

js
let on = false;

function toggle(tab) {
  if (on) {
    browser.sidebarAction.setIcon({
      path: "off.svg",
      tabId: tab.id,
    });
    on = false;
  } else {
    browser.sidebarAction.setIcon({
      path: "on.svg",
      tabId: tab.id,
    });
    on = true;
  }
}

browser.browserAction.onClicked.addListener(toggle);

备注: 此 API 基于 Opera 的 chrome.sidebarAction API。