chrome.browserAction

说明

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

可用性

<ph type="x-smartling-placeholder"></ph> &amp;leq;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 像素（与设备无关）。更大 已调整图标大小以适应屏幕大小，但为了获得最佳效果，请使用 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 字段中），或调用 browserAction.setPopup 方法。

提示

为了获得最佳的视觉冲击力，请遵循以下准则：

  • 务必使用浏览器操作来实现适用于大多数网页的功能。
  • 请勿将浏览器操作用于仅对少数网页有意义的功能。使用页面 操作。
  • 正确做法：使用色彩鲜艳的大图标，充分利用 16x16 深盘空间。浏览器操作图标 看起来应该比页面操作图标略宽一些。
  • 请勿尝试模仿 Google Chrome 的单色菜单图标。这种方法不适合 总而言之，扩展程序也应该与众不同
  • 正确做法：使用 Alpha 透明度为图标添加柔和的边缘。由于很多人都会使用主题 图标在各种背景颜色下都应该美观
  • 请勿一直为图标添加动画效果。真是太烦人了。

示例

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

类型

ColorArray

类型

[数字, 数字, 数字]

ImageDataType

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

类型

ImageData

TabDetails

Chrome 88 及更高版本

属性

  • tabId

    编号（选填）

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

方法

disable()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
)

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

参数

  • tabId

    编号（选填）

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

  • callback

    函数（可选）

    Chrome 67 及更高版本

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 88 及更高版本

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

enable()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
)

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

参数

  • tabId

    编号（选填）

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

  • callback

    函数（可选）

    Chrome 67 及更高版本

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 88 及更高版本

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

getBadgeBackgroundColor()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

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

参数

返回

  • Promise&lt;ColorArray&gt;

    Chrome 88 及更高版本

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

getBadgeText()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
)

获取浏览器操作的标记文本。如果未指定制表符，则系统会返回非制表符特定的标记文本。

参数

  • 详细信息

    TabDetails

  • callback

    函数（可选）

    callback 参数如下所示： 

    (result: string) => void

    • 结果

      字符串

返回

  • 承诺<字符串>

    Chrome 88 及更高版本

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

getPopup()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.browserAction.getPopup(
  details: TabDetails,
  callback?: function,
)

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

参数

  • 详细信息

    TabDetails

  • callback

    函数（可选）

    callback 参数如下所示： 

    (result: string) => void

    • 结果

      字符串

返回

  • 承诺<字符串>

    Chrome 88 及更高版本

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

getTitle()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
)

获取浏览器操作的标题。

参数

  • 详细信息

    TabDetails

  • callback

    函数（可选）

    callback 参数如下所示： 

    (result: string) => void

    • 结果

      字符串

返回

  • 承诺<字符串>

    Chrome 88 及更高版本

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

setBadgeBackgroundColor()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

设置标志的背景颜色。

参数

  • 详细信息

    对象

    • 颜色

      string |ColorArray

      由 0-255 之间的四个整数组成的数组，组成标志的 RGBA 颜色。也可以是包含 CSS 十六进制颜色值的字符串；例如 #FF0000 或 #F00（红色）。以完全不透明度渲染颜色。

    • tabId

      编号（选填）

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

  • callback

    函数（可选）

    Chrome 67 及更高版本

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 88 及更高版本

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

setBadgeText()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
)

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

参数

  • 详细信息

    对象

    • tabId

      编号（选填）

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

    • text

      字符串（可选）

      可以传递任意数量的字符，但空格中只能传递大约 4 个字符。如果传递了空字符串 ('')，则标记文本会被清除。如果指定了 tabId 且 text 为 null，则系统会清除指定标签页的文本，并默认显示全局标志文本。

  • callback

    函数（可选）

    Chrome 67 及更高版本

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 88 及更高版本

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

setIcon()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.browserAction.setIcon(
  details: object,
  callback?: function,
)

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

参数

  • 详细信息

    对象

    • imageData

      ImageData |对象（可选）

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

    • 路径

      string |对象（可选）

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

    • tabId

      编号（选填）

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 116 及更高版本

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

setPopup()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.browserAction.setPopup(
  details: object,
  callback?: function,
)

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

参数

  • 详细信息

    对象

    • 弹出

      字符串

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

    • tabId

      编号（选填）

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

  • callback

    函数（可选）

    Chrome 67 及更高版本

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 88 及更高版本

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

setTitle()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.browserAction.setTitle(
  details: object,
  callback?: function,
)

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

参数

  • 详细信息

    对象

    • tabId

      编号（选填）

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

    • 标题

      字符串

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

  • callback

    函数（可选）

    Chrome 67 及更高版本

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 88 及更高版本

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

事件

onClicked

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

    (tab: tabs.Tab) => void