说明
可用性
在下图中,地址栏右侧的彩色方块是浏览器操作的图标。图标下方会显示一个弹出式窗口。
如果您想创建并非始终有效的图标,请使用页面操作,而不是浏览器操作。
清单
在扩展程序清单中注册浏览器操作,如下所示:
{
"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
属性
-
tabId
数字可选
要查询其状态的标签页的 ID。如果未指定标签页,则返回非标签页专属状态。
方法
disable()
chrome.browserAction.disable(
tabId?: number,
callback?: function,
)
停用标签页的浏览器操作。
参数
-
tabId
数字可选
要为其修改浏览器操作的标签页 ID。
-
callback
函数(可选)
Chrome 67 及更高版本callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 88 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
enable()
chrome.browserAction.enable(
tabId?: number,
callback?: function,
)
为标签页启用浏览器操作。默认值为 enabled。
参数
-
tabId
数字可选
要为其修改浏览器操作的标签页 ID。
-
callback
函数(可选)
Chrome 67 及更高版本callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 88 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getBadgeBackgroundColor()
chrome.browserAction.getBadgeBackgroundColor(
details: TabDetails,
callback?: function,
)
获取浏览器操作的背景颜色。
参数
-
详细信息
-
callback
函数(可选)
callback
参数如下所示:(result: ColorArray) => void
-
结果
-
返回
-
Promise<ColorArray>
Chrome 88 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getBadgeText()
chrome.browserAction.getBadgeText(
details: TabDetails,
callback?: function,
)
获取浏览器操作的标志文本。如果未指定制表符,则返回非制表符专用的标记文字。
参数
-
详细信息
-
callback
函数(可选)
callback
参数如下所示:(result: string) => void
-
结果
string
-
返回
-
Promise<string>
Chrome 88 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getPopup()
chrome.browserAction.getPopup(
details: TabDetails,
callback?: function,
)
获取设置为此浏览器操作的弹出式窗口的 HTML 文档。
参数
-
详细信息
-
callback
函数(可选)
callback
参数如下所示:(result: string) => void
-
结果
string
-
返回
-
Promise<string>
Chrome 88 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getTitle()
chrome.browserAction.getTitle(
details: TabDetails,
callback?: function,
)
获取浏览器操作的标题。
参数
-
详细信息
-
callback
函数(可选)
callback
参数如下所示:(result: string) => void
-
结果
string
-
返回
-
Promise<string>
Chrome 88 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
setBadgeBackgroundColor()
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()
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()
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()
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()
chrome.browserAction.setTitle(
details: object,
callback?: function,
)
设置浏览器操作的标题。此标题会显示在提示中。
参数
-
详细信息
对象
-
tabId
数字可选
将更改限定为选择特定标签页的时间。关闭标签页后自动重置。
-
title
string
鼠标悬停时浏览器操作应显示的字符串。
-
-
callback
函数(可选)
Chrome 67 及更高版本callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 88 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。