说明
使用 chrome.action API 可控制扩展程序在 Google Chrome 工具栏中的图标。
可用性
清单
如需使用 chrome.action API，请将 "manifest_version" 指定为 3，并在清单文件中添加 "action" 键。
{
"name": "Action Extension",
...
"action": {
"default_icon": { // optional
"16": "images/icon16.png", // optional
"24": "images/icon24.png", // optional
"32": "images/icon32.png" // optional
},
"default_title": "Click Me", // optional, shown in tooltip
"default_popup": "popup.html" // optional
},
...
}
"action" 键（及其子键）是可选的。如果未添加此扩展程序，相应扩展程序仍会在工具栏中显示，以便用户访问该扩展程序的菜单。因此，我们建议您始终至少包含 "action" 和 "default_icon" 键。
概念和用法
界面的各个部分
Icon
该图标是扩展程序工具栏中的主图片，由清单的 "action" 键中的 "default_icon" 键设置。图标的宽和高必须为 16 个设备无关像素 (DIP)。
"default_icon" 键是大小与图片路径对应的字典。Chrome 会使用这些图标来选择要使用的图片缩放比例。如果未找到完全匹配的结果，Chrome 会选择最接近的可用图片并对其进行缩放以适合图片，这可能会影响图片质量。
由于 1.5 倍或 1.2 倍等不太常见的缩放比例设备越来越常见，因此我们建议您提供多种尺寸的图标。这还可以确保扩展程序的未来不会发生可能的图标显示大小变化。
您也可以调用 action.setIcon()，从而以编程方式设置扩展程序的图标，方法是指定不同的图片路径，或使用 HTML 画布元素提供动态生成的图标，或者调用屏幕外画布 API（如果通过扩展程序 Service Worker 进行设置）。
const canvas = new OffscreenCanvas(16, 16);
const context = canvas.getContext('2d');
context.clearRect(0, 0, 16, 16);
context.fillStyle = '#00FF00'; // Green
context.fillRect(0, 0, 16, 16);
const imageData = context.getImageData(0, 0, 16, 16);
chrome.action.setIcon({imageData: imageData}, () => { /* ... */ });
对于打包的扩展程序（通过 .crx 文件安装），图片可以采用 Blink 渲染引擎可以显示的大多数格式，包括 PNG、JPEG、BMP、ICO 等。但不支持 SVG。 未封装的扩展程序必须使用 PNG 图片。
提示（标题）
用户将鼠标指针悬停在工具栏中的扩展程序图标上时，系统会显示提示或标题。当相应按钮获得焦点时，它也会包含在屏幕阅读器朗读的无障碍文本中。
默认提示是使用 manifest.json 中 "action" 键的 "default_title" 字段设置的。您还可以通过调用 action.setTitle() 以编程方式进行设置。
徽章
操作可以选择性地显示“标志”，即在图标上叠加的少量文本。这样一来，您就可以更新操作，以显示少量有关扩展程序状态的信息，例如计数器。该标志包含一个文本组件和一种背景颜色。由于空间有限，我们建议标志文本使用不超过 4 个字符。
如需创建标志，请调用 action.setBadgeBackgroundColor() 和 action.setBadgeText() 以编程方式进行设置。清单中没有默认的标记设置。标记颜色值可以是包含 0 到 255 之间的四个整数的数组（构成标记的 RGBA 颜色），也可以是具有 CSS 颜色值的字符串。
chrome.action.setBadgeBackgroundColor(
{color: [0, 255, 0, 0]}, // Green
() => { /* ... */ },
);
chrome.action.setBadgeBackgroundColor(
{color: '#00FF00'}, // Also green
() => { /* ... */ },
);
chrome.action.setBadgeBackgroundColor(
{color: 'green'}, // Also, also green
() => { /* ... */ },
);
弹出式窗口
用户点击工具栏中的扩展程序的操作按钮时，系统会显示操作的弹出式窗口。此弹出式窗口可包含您喜欢的任何 HTML 内容，并且会根据其内容自动调整大小。弹出式窗口的尺寸必须介于 25x25 到 800x600 像素之间。
弹出式窗口最初由 manifest.json 文件的 "action" 键中的 "default_popup" 属性设置。如果存在，此属性应指向扩展目录中的相对路径。您还可以使用 action.setPopup() 方法动态更新该路径，以指向其他相对路径。
用例
每个标签页的状态
每个标签页的扩展程序操作可以有不同的状态。如需为单个标签页设置值，请使用 action API 设置方法中的 tabId 属性。例如，如需为特定标签页设置标记文本，请执行以下操作：
function getTabId() { /* ... */}
function getTabBadge() { /* ... */}
chrome.action.setBadgeText(
{
text: getTabBadge(tabId),
tabId: getTabId(),
},
() => { ... }
);
如果未添加 tabId 属性，系统会将此设置视为全局设置。特定于标签页的设置优先于全局设置。
启用状态
默认情况下，每个标签页上的工具栏操作都处于启用状态（可点击）。您可以使用 action.enable() 和 action.disable() 方法控制此行为。这只会影响系统是否将弹出式窗口（如果有）或 action.onClicked 事件发送到您的扩展程序，而不会影响相应操作是否显示在工具栏中。
示例
以下示例展示了在扩展程序中使用操作的一些常见方式。如需试用此 API，请从 chrome-extension-samples 代码库安装 Action API 示例。
显示弹出式窗口
当用户点击某个扩展程序的操作时，该扩展程序会显示一个弹出式窗口，这种现象很常见。如需在您自己的扩展程序中实现这一点，请在 manifest.json 中声明弹出式窗口，并指定 Chrome 应在弹出式窗口中显示的内容。
// manifest.json
{
"name": "Action popup demo",
"version": "1.0",
"manifest_version": 3,
"action": {
"default_title": "Click to view a popup",
"default_popup": "popup.html"
}
}
<!-- popup.html -->
<!DOCTYPE html>
<html>
<head>
<style>
html {
min-height: 5em;
min-width: 10em;
background: salmon;
}
</style>
</head>
<body>
<p>Hello, world!</p>
</body>
</html>
点击时注入内容脚本
扩展程序的常见模式是使用扩展程序的操作公开其主要功能。以下示例演示了此模式。当用户点击该操作时，该扩展程序会将内容脚本注入当前页面。然后，内容脚本会显示一条提醒，以验证一切是否按预期运行。
// manifest.json
{
"name": "Action script injection demo",
"version": "1.0",
"manifest_version": 3,
"action": {
"default_title": "Click to show an alert"
},
"permissions": ["activeTab", "scripting"],
"background": {
"service_worker": "background.js"
}
}
// background.js
chrome.action.onClicked.addListener((tab) => {
chrome.scripting.executeScript({
target: {tabId: tab.id},
files: ['content.js']
});
});
// content.js
alert('Hello, world!');
使用 declarativeContent 模拟操作
此示例展示了扩展程序的后台逻辑如何 (a) 默认停用某项操作，并 (b) 使用 declarativeContent 在特定网站上启用该操作。
// service-worker.js
// Wrap in an onInstalled callback to avoid unnecessary work
// every time the service worker is run
chrome.runtime.onInstalled.addListener(() => {
// Page actions are disabled by default and enabled on select tabs
chrome.action.disable();
// Clear all rules to ensure only our expected rules are set
chrome.declarativeContent.onPageChanged.removeRules(undefined, () => {
// Declare a rule to enable the action on example.com pages
let exampleRule = {
conditions: [
new chrome.declarativeContent.PageStateMatcher({
pageUrl: {hostSuffix: '.example.com'},
})
],
actions: [new chrome.declarativeContent.ShowAction()],
};
// Finally, apply our new array of rules
let rules = [exampleRule];
chrome.declarativeContent.onPageChanged.addRules(rules);
});
});
类型
OpenPopupOptions
属性
-
windowId
数字可选
打开操作弹出式窗口的窗口的 ID。如果未指定，则默认为当前活动窗口。
TabDetails
属性
-
tabId
数字可选
要查询其状态的标签页的 ID。如果未指定标签页，则返回非标签页专属状态。
UserSettings
与扩展程序操作相关的用户指定设置的集合。
属性
-
isOnToolbar
boolean
扩展程序的操作图标是否显示在浏览器窗口的顶层工具栏中（即用户是否已“固定”扩展程序）。
方法
disable()
chrome.action.disable(
tabId?: number,
callback?: function,
)
停用标签页操作。
参数
-
tabId
数字可选
要修改其操作的标签页的 ID。
-
callback
函数（可选）
callback参数如下所示：()=>void
返回
-
Promise<void>
Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
enable()
chrome.action.enable(
tabId?: number,
callback?: function,
)
为标签页启用操作。默认情况下，操作处于启用状态。
参数
-
tabId
数字可选
要修改其操作的标签页的 ID。
-
callback
函数（可选）
callback参数如下所示：()=>void
返回
-
Promise<void>
Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
getBadgeBackgroundColor()
chrome.action.getBadgeBackgroundColor(
details: TabDetails,
callback?: function,
)
获取操作的背景颜色。
参数
-
明细
-
callback
函数（可选）
callback参数如下所示：(result: ColorArray)=>void
-
结果
-
返回
-
Promise<browserAction.ColorArray>
Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
getBadgeText()
chrome.action.getBadgeText(
details: TabDetails,
callback?: function,
)
获取操作的标志文本。如果未指定制表符，则返回非制表符专用的标记文字。如果启用了 displayActionCountAsBadgeText，则系统将返回占位文本，除非具有 declarativeNetRequestFeedback 权限或提供了标签页专用的标记文本。
参数
-
明细
-
callback
函数（可选）
callback参数如下所示：(result: string)=>void
-
结果
string
-
返回
-
Promise<string>
Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
getBadgeTextColor()
chrome.action.getBadgeTextColor(
details: TabDetails,
callback?: function,
)
获取操作的文本颜色。
参数
-
明细
-
callback
函数（可选）
callback参数如下所示：(result: ColorArray)=>void
-
结果
-
返回
-
Promise<browserAction.ColorArray>
Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
getPopup()
chrome.action.getPopup(
details: TabDetails,
callback?: function,
)
获取设置为此操作的弹出式窗口的 HTML 文档。
参数
-
明细
-
callback
函数（可选）
callback参数如下所示：(result: string)=>void
-
结果
string
-
返回
-
Promise<string>
Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
参数
-
明细
-
callback
函数（可选）
callback参数如下所示：(result: string)=>void
-
结果
string
-
返回
-
Promise<string>
Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
getUserSettings()
chrome.action.getUserSettings(
callback?: function,
)
返回与扩展程序操作相关的用户指定设置。
参数
-
callback
函数（可选）
callback参数如下所示：(userSettings: UserSettings)=>void
-
userSettings
-
返回
-
Promise<UserSettings>
Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
isEnabled()
chrome.action.isEnabled(
tabId?: number,
callback?: function,
)
指示是否为标签页启用了扩展程序操作（或者，如果未提供 tabId，则使用全局操作）。仅使用 declarativeContent 启用的操作始终返回 false。
参数
-
tabId
数字可选
要检查其启用状态的标签页的 ID。
-
callback
函数（可选）
callback参数如下所示：(isEnabled: boolean)=>void
-
isEnabled
boolean
如果启用了扩展程序操作，则为 true。
-
返回
-
Promise<boolean>
Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
openPopup()
chrome.action.openPopup(
options?: OpenPopupOptions,
callback?: function,
)
打开扩展程序的弹出式窗口。
参数
-
选项
指定用于打开弹出式窗口的选项。
-
callback
函数（可选）
callback参数如下所示：()=>void
返回
-
Promise<void>
Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
setBadgeBackgroundColor()
chrome.action.setBadgeBackgroundColor(
details: object,
callback?: function,
)
设置标志的背景颜色。
参数
-
明细
对象
-
颜色
字符串|ColorArray
一个由 [0,255] 范围内的四个整数构成的数组，这些整数构成了徽章的 RGBA 颜色。例如，不透明的红色为
[255, 0, 0, 255]。也可以是具有 CSS 值的字符串，其中不透明的红色值为#FF0000或#F00。 -
tabId
数字可选
将更改限定为选择特定标签页的时间。关闭标签页后自动重置。
-
-
callback
函数（可选）
callback参数如下所示：()=>void
返回
-
Promise<void>
Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
setBadgeText()
chrome.action.setBadgeText(
details: object,
callback?: function,
)
设置操作的标志文本。标记会显示在图标顶部。
参数
-
明细
对象
-
tabId
数字可选
将更改限定为选择特定标签页的时间。关闭标签页后自动重置。
-
text
字符串（可选）
可以传递任意数量的字符，但空间中只能包含大约 4 个字符。如果传递了空字符串 (
'')，标记文本将被清除。如果指定了tabId且text为 null，则指定标签页的文本会清除，并默认为全局标记文本。
-
-
callback
函数（可选）
callback参数如下所示：()=>void
返回
-
Promise<void>
Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
setBadgeTextColor()
chrome.action.setBadgeTextColor(
details: object,
callback?: function,
)
设置标志的文字颜色。
参数
-
明细
对象
-
颜色
字符串|ColorArray
一个由 [0,255] 范围内的四个整数构成的数组，这些整数构成了徽章的 RGBA 颜色。例如，不透明的红色为
[255, 0, 0, 255]。也可以是具有 CSS 值的字符串，其中不透明的红色值为#FF0000或#F00。如果不设置此值，系统会自动选择与徽章的背景颜色形成鲜明对比的颜色，从而使文本可见。不会设置 alpha 值等于 0 的颜色，并且将返回错误。 -
tabId
数字可选
将更改限定为选择特定标签页的时间。关闭标签页后自动重置。
-
-
callback
函数（可选）
callback参数如下所示：()=>void
返回
-
Promise<void>
Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
setIcon()
chrome.action.setIcon(
details: object,
callback?: function,
)
设置操作的图标。可将图标指定为图像文件的路径或画布元素的像素数据，或者指定这些图标的字典。必须指定 path 或 imageData 属性。
参数
-
明细
对象
-
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
数字可选
将更改限定为选择特定标签页的时间。关闭标签页后自动重置。
-
-
callback
函数（可选）
callback参数如下所示：()=>void
返回
-
Promise<void>
Chrome 96 及更高版本Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
setPopup()
chrome.action.setPopup(
details: object,
callback?: function,
)
设置 HTML 文档，使其在用户点击操作的图标时以弹出式窗口形式打开。
参数
-
明细
对象
-
弹出式内容（窗口/广告/etc.）
string
要在弹出式窗口中显示的 HTML 文件的相对路径。如果设置为空字符串 (
'')，则不会显示弹出式窗口。 -
tabId
数字可选
将更改限定为选择特定标签页的时间。关闭标签页后自动重置。
-
-
callback
函数（可选）
callback参数如下所示：()=>void
返回
-
Promise<void>
Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
setTitle()
chrome.action.setTitle(
details: object,
callback?: function,
)
设置操作的标题。这会显示在提示中。
参数
-
明细
对象
-
tabId
数字可选
将更改限定为选择特定标签页的时间。关闭标签页后自动重置。
-
title
string
鼠标悬停时操作应显示的字符串。
-
-
callback
函数（可选）
callback参数如下所示：()=>void
返回
-
Promise<void>
Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。