chrome.browserAction

说明

可用性

在下图中，地址栏右侧的彩色方块是浏览器操作的图标。图标下方会显示一个弹出式窗口。

如果您想创建一个非始终处于活动状态的图标，请使用网页操作，而不是浏览器操作。

清单

在扩展程序清单中注册您的浏览器操作，如下所示：

{
  "name": "My extension",
  ...
  "browser_action": {
    "default_icon": {                // optional
      "16": "images/icon16.png",     // optional
      "24": "images/icon24.png",     // optional
      "32": "images/icon32.png"      // optional
    },
    "default_title": "Google Mail",  // optional, shown in tooltip
    "default_popup": "popup.html"    // optional
  },
  ...
}

您可以提供要用于 Chrome 的任何尺寸的图标，Chrome 会选择最接近的图标，并将其放大到适当的尺寸以填充 16 像素的空间。不过，如果未提供确切尺寸，此缩放可能会导致图标失去细节或看起来模糊不清。

由于采用不太常见的缩放比例（例如 1.5x 或 1.2x）的设备越来越多，因此我们建议您为图标提供多种尺寸。这还可确保，如果图标显示大小发生变化，您无需执行任何其他工作即可提供不同的图标！

系统仍支持用于注册默认图标的旧版语法：

{
  "name": "My extension",
  ...
  "browser_action": {
    ...
    "default_icon": "images/icon32.png"  // optional
    // equivalent to "default_icon": { "32": "images/icon32.png" }
  },
  ...
}

界面的各个部分

浏览器操作可以包含图标、提示、徽章和弹出式窗口。

图标

Chrome 中的浏览器操作图标的宽度和高度均为 16 dip（设备无关像素）。系统会调整较大的图标大小以适应，但为获得最佳效果，请使用 16 像素的方形图标。

您可以通过以下两种方式设置图标：使用静态图片或使用 HTML5 画布元素。对于简单的应用，使用静态图片更为简单，但您可以使用画布元素创建更具动态效果的界面（例如流畅的动画）。

静态图片可以采用 WebKit 可以显示的任何格式，包括 BMP、GIF、ICO、JPEG 或 PNG。对于已解压缩的扩展程序，图片必须采用 PNG 格式。

如需设置图标，请使用清单中的 default_icon 的 default_icon 字段，或调用 browserAction.setIcon 方法。

为了在屏幕像素密度（比率 size_in_pixel / size_in_dip）不同于 1 时正确显示图标，可以将图标定义为一组尺寸不同的图片。系统会从该组中选择最适合 16 dip 像素大小的实际图片进行显示。图标集可以包含任何尺寸的图标规范，Chrome 会选择最合适的图标。

提示

如需设置提示，请使用清单中的 default_title 的 default_title 字段，或调用 browserAction.setTitle 方法。您可以为 default_title 字段指定特定于语言区域的字符串；如需了解详情，请参阅国际化。

徽章

浏览器操作可以选择显示标记，即叠加在图标上的文本。借助标记，您可以轻松更新浏览器操作，以显示有关扩展程序状态的少量信息。

由于徽章的空间有限，因此徽章应不超过 4 个字符。

分别使用 browserAction.setBadgeText 和 browserAction.setBadgeBackgroundColor 设置徽章的文本和颜色。

弹出式窗口

如果浏览器操作包含弹出式窗口，则当用户点击扩展程序的图标时，系统会显示该弹出式窗口。该弹出式窗口可以包含您喜欢的任何 HTML 内容，并且会自动调整大小以适应其内容。弹出式窗口的尺寸不得小于 25x25，也不得大于 800x600。

如需向浏览器操作添加弹出式窗口，请创建一个包含弹出式窗口内容的 HTML 文件。在清单的 default_popup 的 default_popup 字段中指定 HTML 文件，或调用 browserAction.setPopup 方法。

提示

为了获得最佳视觉效果，请遵循以下准则：

• 对于在大多数网页上都适用的功能，请使用浏览器操作。
• 请勿针对仅适用于少数网页的功能使用浏览器操作。改用页面操作。
• 应使用色彩鲜艳的大图标，充分利用 16x16 像素的空间。浏览器操作图标应比网页操作图标略大且更醒目。
• 请勿尝试模仿 Google Chrome 的单色菜单图标。这不适用于主题，而且无论如何，扩展程序都应稍微突出一些。
• 使用 Alpha 透明度为图标添加柔边。由于许多用户使用主题，因此您的图标应在各种背景颜色上看起来都很不错。
• 不要让图标持续呈现动画效果。这很烦人。

示例

您可以在 examples/api/browserAction 目录中找到使用浏览器操作的简单示例。如需查看其他示例以及有关查看源代码的帮助，请参阅示例。

chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
)

chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
)

chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
)

chrome.browserAction.getPopup(
  details: TabDetails,
  callback?: function,
)

chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
)

chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
)

chrome.browserAction.setIcon(
  details: object,
  callback?: function,
)

chrome.browserAction.setPopup(
  details: object,
  callback?: function,
)

chrome.browserAction.setTitle(
  details: object,
  callback?: function,
)

chrome.browserAction.onClicked.addListener(
  callback: function,
)