说明
使用 chrome.pageAction
API 将图标放置在 Google Chrome 主工具栏中,位于地址栏的右侧。网页操作表示可在当前网页上进行,但不适用于所有网页的操作。网页操作在闲置时会显示为灰色。
可用性
部分示例:
- 订阅此页面的 RSS Feed
- 利用此页面的照片制作幻灯片
以下屏幕截图中的 RSS 图标表示一项网页操作,可让您订阅当前网页的 RSS Feed。
隐藏的页面操作呈灰显状态。例如,下面的 RSS Feed 会灰显,因为您无法订阅当前页面的 Feed:
请考虑改用浏览器操作,以便用户始终能与您的扩展程序互动。
清单
在扩展程序清单中注册您的页面操作,如下所示:
{
"name": "My extension",
...
"page_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
},
...
}
由于缩放比例不那么常见的设备(如 1.5 倍或 1.2 倍)越来越常见,因此我们建议您提供多种尺寸的图标。Chrome 会选择最近的一个并对其进行缩放,以填充 16 dip 空间。这还可确保,如果图标显示大小发生变化,您无需执行任何其他操作即可提供不同的图标!但是,如果大小差异过大,这种缩放可能会导致图标丢失细节或看起来模糊不清。
我们仍支持用于注册默认图标的旧语法:
{
"name": "My extension",
...
"page_action": {
...
"default_icon": "images/icon32.png" // optional
// equivalent to "default_icon": { "32": "images/icon32.png" }
},
...
}
界面的各个部分
与浏览器操作一样,页面操作也可以具有图标、提示和弹出式窗口;但它们不能有标记。此外,网页操作可能会灰显。您可以参阅浏览器操作界面,了解有关图标、提示和弹出式窗口的信息。
您可以分别使用 pageAction.show
和 pageAction.hide
方法使网页操作显示和灰显。默认情况下,网页操作会显示为灰色。显示图标时,您可以指定应在其中显示该图标的标签页。该图标会一直显示,直到该标签页关闭或开始显示其他网址(例如,因为用户点击了链接)。
提示
为了获得最佳视觉冲击效果,请遵循以下准则:
- 务必对仅适用于少数网页的功能使用网页操作。
- 请勿对适合大多数网页的功能使用网页操作。请改用浏览器操作。
- 请勿持续为图标添加动画效果。真是太烦了。
类型
ImageDataType
图片的像素数据。必须是 ImageData 对象(例如,来自 canvas
元素中)。
类型
ImageData
TabDetails
属性
-
tabId
数字可选
要查询其状态的标签页的 ID。如果未指定标签页,则返回非标签页专属状态。
方法
getPopup()
chrome.pageAction.getPopup(
details: TabDetails,
callback?: function,
)
获取设置为此页面操作的弹出式窗口的 HTML 文档。
参数
-
详细信息
-
callback
函数(可选)
callback
参数如下所示:(result: string) => void
-
结果
string
-
返回
-
Promise<string>
Chrome 101 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getTitle()
chrome.pageAction.getTitle(
details: TabDetails,
callback?: function,
)
获取网页操作的标题。
参数
-
详细信息
-
callback
函数(可选)
callback
参数如下所示:(result: string) => void
-
结果
string
-
返回
-
Promise<string>
Chrome 101 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
hide()
chrome.pageAction.hide(
tabId: number,
callback?: function,
)
隐藏网页操作。隐藏的页面操作仍会显示在 Chrome 工具栏中,但会灰显。
参数
-
tabId
number
您要修改其网页操作的标签页 ID。
-
callback
函数(可选)
Chrome 67 及更高版本callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 101 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
setIcon()
chrome.pageAction.setIcon(
details: object,
callback?: function,
)
设置网页操作的图标。可将图标指定为图像文件的路径或画布元素的像素数据,或者指定这些图标的字典。必须指定 path 或 imageData 属性。
参数
-
详细信息
对象
-
iconIndex
数字可选
已弃用。系统会忽略此参数。
-
imageData
ImageData | 对象可选
ImageData 对象或表示要设置的图标的字典 {size -> ImageData}。如果以字典形式指定图标,则系统会根据屏幕的像素密度选择要使用的实际图像。如果一个屏幕空间单位可容纳的图片像素数等于
scale
,则系统会选择尺寸为scale
* n 的图片,其中 n 表示界面中图标的尺寸。必须至少指定一张图片。请注意,“details.imageData = foo”等同于“details.imageData = {'16': foo}” -
path
string | 对象 可选
相对图片路径或指向要设置的图标的字典 {size -> relative image path}。如果以字典形式指定图标,则系统会根据屏幕的像素密度选择要使用的实际图像。如果一个屏幕空间单位可容纳的图片像素数等于
scale
,则系统会选择尺寸为scale
* n 的图片,其中 n 表示界面中图标的尺寸。必须至少指定一张图片。请注意,“details.path = foo”等同于“details.path = {'16': foo}” -
tabId
number
您要修改其网页操作的标签页 ID。
-
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 101 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
setPopup()
chrome.pageAction.setPopup(
details: object,
callback?: function,
)
设置 HTML 文档,使其在用户点击页面操作的图标时以弹出式窗口形式打开。
参数
-
详细信息
对象
-
弹出式内容(窗口/广告/etc.)
string
要在弹出式窗口中显示的 HTML 文件的相对路径。如果设置为空字符串 (
''
),则不会显示弹出式窗口。 -
tabId
number
您要修改其网页操作的标签页 ID。
-
-
callback
函数(可选)
Chrome 67 及更高版本callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 101 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
setTitle()
chrome.pageAction.setTitle(
details: object,
callback?: function,
)
设置网页操作的标题。这会显示在网页操作上方的提示中。
参数
-
详细信息
对象
-
tabId
number
您要修改其网页操作的标签页 ID。
-
title
string
提示字符串。
-
-
callback
函数(可选)
Chrome 67 及更高版本callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 101 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
show()
chrome.pageAction.show(
tabId: number,
callback?: function,
)
显示网页操作。每当选中该标签页时,系统都会显示网页操作。
参数
-
tabId
number
您要修改其网页操作的标签页 ID。
-
callback
函数(可选)
Chrome 67 及更高版本callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 101 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。