chrome.browserAction

refresh date: 2026-09-25 robots: noindex

说明

使用浏览器操作将图标放置在 Google Chrome 主工具栏中（地址栏右侧）。除了图标之外，浏览器操作还可以有提示、标记和弹出式窗口。

可用性

≤ MV2

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

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

清单

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

{
  "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 元素创建更具动态效果的界面（例如流畅的动画）。

静态图片可以是 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 目录中找到使用浏览器操作的简单示例。如需查看其他示例以及查看源代码方面的帮助，请参阅示例。

类型

TabDetails

Chrome 88 及更高版本

属性

  • tabId

    number 可选

    要查询其状态的标签页的 ID。如果未指定标签页，则系统会返回非标签页专用状态。

方法

disable()

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

停用标签页的浏览器操作。

参数

  • tabId

    number 可选

    要修改其浏览器操作的标签页的 ID。

  • callback

    函数可选

    Chrome 67 及更高版本

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

enable()

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

为标签页启用浏览器操作。默认值为 enabled。

参数

  • tabId

    number 可选

    要修改其浏览器操作的标签页的 ID。

  • callback

    函数可选

    Chrome 67 及更高版本

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getBadgeBackgroundColor()

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

获取浏览器操作的背景颜色。

参数

返回

  • Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getBadgeText()

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

获取浏览器操作的标记文字。如果未指定标签页，则系统会返回非标签页专用标记文本。

参数

  • 详细信息

    TabDetails

  • callback

    函数可选

    callback 参数如下所示： 

    (result: string) => void

    • 结果

      字符串

返回

  • Promise<string>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getPopup()

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

获取设置为此浏览器操作的弹出式窗口的 HTML 文档。

参数

  • 详细信息

    TabDetails

  • callback

    函数可选

    callback 参数如下所示： 

    (result: string) => void

    • 结果

      字符串

返回

  • Promise<string>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getTitle()

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

获取浏览器操作的标题。

参数

  • 详细信息

    TabDetails

  • callback

    函数可选

    callback 参数如下所示： 

    (result: string) => void

    • 结果

      字符串

返回

  • Promise<string>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

setBadgeBackgroundColor()

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

设置徽章的背景颜色。

参数

  • 详细信息

    对象

    • 颜色

      字符串 | ColorArray

      由 4 个整数（范围为 0-255）组成的数组，用于构成徽章的 RGBA 颜色。也可以是包含 CSS 十六进制颜色码值的字符串，例如 #FF0000 或 #F00（红色）。以完全不透明的方式渲染颜色。

    • tabId

      number 可选

      仅在选择特定标签页时应用更改。在标签页关闭时自动重置。

  • callback

    函数可选

    Chrome 67 及更高版本

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

setBadgeText()

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

设置浏览器操作的标志文字。该标记会显示在图标顶部。

参数

  • 详细信息

    对象

    • tabId

      number 可选

      仅在选择特定标签页时应用更改。在标签页关闭时自动重置。

    • text

      字符串 可选

      您可以传递任意数量的字符，但该空间只能容纳大约四个字符。如果传递空字符串 ('')，则会清除标记文本。如果指定了 tabId，但 text 为 null，则指定标签页的文本会被清除，并默认设为全局标志文本。

  • callback

    函数可选

    Chrome 67 及更高版本

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

setIcon()

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

设置浏览器操作的图标。图标可以指定为图片文件的路径、画布元素的像素数据，或其中之一的字典。必须指定 path 或 imageData 属性。

参数

  • 详细信息

    对象

    • imageData

      ImageData | 对象 可选

      ImageData 对象或字典 {size -> ImageData}，表示要设置的图标。如果图标指定为字典，则系统会根据屏幕的像素密度选择要使用的图片。如果一个屏幕空间单位可容纳的图片像素数为 scale，则系统会选择大小为 scale * n 的图片，其中 n 是界面中图标的大小。必须至少指定一张图片。请注意，“details.imageData = foo”等同于“details.imageData = {'16': foo}”

    • 路径

      字符串 | 对象 可选

      相对图片路径或字典 {size -> relative image path}，指向要设置的图标。如果图标指定为字典，则系统会根据屏幕的像素密度选择要使用的图片。如果一个屏幕空间单位可容纳的图片像素数量等于 scale，则系统会选择大小为 scale * n 的图片，其中 n 是界面中图标的大小。必须至少指定一张图片。请注意，“details.path = foo”等同于“details.path = {'16': foo}”

    • tabId

      number 可选

      仅在选择特定标签页时应用更改。在标签页关闭时自动重置。

  • callback

    函数可选

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 116 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

setPopup()

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

设置当用户点击浏览器操作图标时，要作为弹出式窗口打开的 HTML 文档。

参数

  • 详细信息

    对象

    • 弹出

      字符串

      要在弹出式窗口中显示的 HTML 文件的相对路径。如果设置为空字符串 ('')，则不会显示任何弹出式窗口。

    • tabId

      number 可选

      仅在选择特定标签页时应用更改。在标签页关闭时自动重置。

  • callback

    函数可选

    Chrome 67 及更高版本

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

setTitle()

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

设置浏览器操作的标题。此标题会显示在提示中。

参数

  • 详细信息

    对象

    • tabId

      number 可选

      仅在选择特定标签页时应用更改。在标签页关闭时自动重置。

    • title

      字符串

      鼠标悬停在浏览器操作上时应显示的字符串。

  • callback

    函数可选

    Chrome 67 及更高版本

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 88 及更高版本

    只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

事件

onClicked

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

当用户点击浏览器操作图标时触发。如果浏览器操作有弹出式窗口，则不会触发。

参数

  • callback

    函数

    callback 参数如下所示： 

    (tab: tabs.Tab) => void