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-dip 的空间。不过，如果未提供确切尺寸，这种缩放可能会导致图标丢失细节或看起来模糊不清。

由于具有不太常见缩放比例（例如 1.5 倍或 1.2 倍）的设备越来越常见，因此建议您为图标提供多种尺寸。这样一来，即使图标显示尺寸发生变化，您也不需要再做任何工作来提供不同的图标！

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

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

界面组成部分

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

图标

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

您可以通过两种方式设置图标：使用静态图片或使用 HTML5 canvas 元素。对于简单的应用，使用静态图片会更轻松，但您可以使用 canvas 元素创建更动态的界面，例如流畅的动画。

静态图片可以是 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-dip 的空间。浏览器操作图标应比网页操作图标略大且略重。
• 请勿尝试模仿 Google Chrome 的单色菜单图标。这与主题不太搭调，而且无论如何，扩展程序都应该稍微突出显示。
• 请使用 Alpha 透明度为图标添加柔和的边缘。由于许多人会使用主题，因此您的图标应在各种背景色下都看起来不错。
• 错误做法：不要让图标持续显示动画。这只会让人感到烦恼。

示例

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

chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
): Promise<void>

chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
): Promise<void>

chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
): Promise<extensionTypes.ColorArray>

chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
): Promise<string>

chrome.browserAction.getPopup(
  details: TabDetails,
  callback?: function,
): Promise<string>

chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
): Promise<string>

chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
): Promise<void>

chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
): Promise<void>

chrome.browserAction.setIcon(
  details: object,
  callback?: function,
): Promise<void>

chrome.browserAction.setPopup(
  details: object,
  callback?: function,
): Promise<void>

chrome.browserAction.setTitle(
  details: object,
  callback?: function,
): Promise<void>

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