chrome.browserAction

说明

使用浏览器操作将图标放置在 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 度的屏幕空间。但是，如果未提供确切尺寸，这种缩放可能会导致图标丢失细节或看起来模糊不清。

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

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

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

界面的各个部分

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

Icon

Chrome 中的浏览器操作图标宽和高均为 16（与设备无关的像素）。较大的图标会调整大小以适应相应尺寸，但为了达到最佳效果，请使用 16 dip 方形图标。

您可以通过两种方式设置图标：使用静态图片或使用 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 目录中找到使用浏览器操作的简单示例。如需查看其他示例以及在查看源代码方面获得帮助，请参阅示例。

类型

ColorArray

类型

[数值,数值,数值,数值]

ImageDataType

图片的像素数据。必须是 ImageData 对象；例如，来自 canvas 元素。

类型

ImageData

TabDetails

Chrome 88 及更高版本

属性

  • tabId

    数字可选

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

方法

disable()

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

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

参数

  • tabId

    数字可选

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

  • callback

    函数（可选）

    Chrome 67 及更高版本

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 88 及更高版本

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

enable()

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

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

参数

  • tabId

    数字可选

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

  • callback

    函数（可选）

    Chrome 67 及更高版本

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 88 及更高版本

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

getBadgeBackgroundColor()

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

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

参数

返回

  • Promise<ColorArray>

    Chrome 88 及更高版本

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

getBadgeText()

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

获取浏览器操作的标志文本。如果未指定制表符，则返回非制表符专用的标记文字。

参数

  • 明细

    TabDetails

  • callback

    函数（可选）

    callback 参数如下所示：

    (result: string)=>void

    • 结果

      string

返回

  • Promise<string>

    Chrome 88 及更高版本

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

getPopup()

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

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

参数

  • 明细

    TabDetails

  • callback

    函数（可选）

    callback 参数如下所示：

    (result: string)=>void

    • 结果

      string

返回

  • Promise<string>

    Chrome 88 及更高版本

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

getTitle()

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

获取浏览器操作的标题。

参数

  • 明细

    TabDetails

  • callback

    函数（可选）

    callback 参数如下所示：

    (result: string)=>void

    • 结果

      string

返回

  • Promise<string>

    Chrome 88 及更高版本

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

setBadgeBackgroundColor()

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

设置标志的背景颜色。

参数

  • 明细

    对象

    • 颜色

      字符串|ColorArray

      一个数组，包含 0-255 范围内的四个整数，构成了徽章的 RGBA 颜色。也可以是包含 CSS 十六进制颜色值的字符串；例如 #FF0000 或 #F00（红色）。以完全不透明度渲染颜色。

    • tabId

      数字可选

      将更改限定为选择特定标签页的时间。关闭标签页后自动重置。

  • callback

    函数（可选）

    Chrome 67 及更高版本

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 88 及更高版本

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

setBadgeText()

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

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

参数

  • 明细

    对象

    • tabId

      数字可选

      将更改限定为选择特定标签页的时间。关闭标签页后自动重置。

    • text

      字符串（可选）

      可以传递任意数量的字符，但只能在 4 个字符之间传递。如果传递了空字符串 ('')，标记文本将被清除。如果指定了 tabId 且 text 为 null，则指定标签页的文本会清除，并默认为全局标记文本。

  • callback

    函数（可选）

    Chrome 67 及更高版本

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 88 及更高版本

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

setIcon()

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

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

参数

  • 明细

    对象

    • imageData

      ImageData|对象 可选

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

    • path

      string|对象 可选

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

    • tabId

      数字可选

      将更改限定为选择特定标签页的时间。关闭标签页后自动重置。

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 116 及更高版本

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

setPopup()

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

设置 HTML 文档，在用户点击浏览器操作图标时以弹出式窗口形式打开。

参数

  • 明细

    对象

    • 弹出式内容（窗口/广告/etc.）

      string

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

    • tabId

      数字可选

      将更改限定为选择特定标签页的时间。关闭标签页后自动重置。

  • callback

    函数（可选）

    Chrome 67 及更高版本

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 88 及更高版本

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

setTitle()

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

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

参数

  • 明细

    对象

    • tabId

      数字可选

      将更改限定为选择特定标签页的时间。关闭标签页后自动重置。

    • title

      string

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

  • callback

    函数（可选）

    Chrome 67 及更高版本

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 88 及更高版本

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

活动

onClicked

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

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

参数

  • callback

    功能

    callback 参数如下所示：

    (tab: tabs.Tab)=>void