此页面由 Cloud Translation API 翻译。

chrome.action

说明

使用 chrome.action API 控制 Google Chrome 工具栏中的扩展程序图标。

操作图标显示在浏览器工具栏中的 omnibox 旁边。安装后，这些扩展程序会显示在扩展程序菜单（拼图图标）中。用户可以将您的扩展程序图标固定到工具栏。

可用性

Chrome 88 及更高版本 MV3 及更高版本

清单

如需使用此 API，必须在清单中声明以下键。

"action"

如需使用 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" 键。

概念和用法

界面组成部分

图标

该图标是扩展程序工具栏上的主要图片，由清单的 "action" 键中的 "default_icon" 键设置。图标的宽度和高度必须为 16 个与设备无关的像素 (DIP)。

"default_icon" 键是一个包含大小到图片路径的字典。Chrome 会使用这些图标来选择要使用的图片缩放比例。如果找不到完全匹配的图片，Chrome 会选择最接近的可用图片并将其缩放为适合的尺寸，这可能会影响图片质量。

由于具有 1.5 倍或 1.2 倍等不太常见缩放比例的设备越来越普遍，我们建议您为图标提供多种尺寸。这还可以确保您的扩展程序在未来能够应对潜在的图标显示大小变化。不过，如果只提供一种尺寸，也可以将 "default_icon" 键设置为指向单个图标路径的字符串，而不是字典。

您还可以通过指定其他图片路径或使用 HTML canvas 元素（如果从扩展程序服务工作线程进行设置，则使用 offscreen canvas API）提供动态生成的图标，以通过编程方式调用 action.setIcon() 来设置扩展程序的图标。

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}, () => { /* ... */ });

注意：action.setIcon() API 旨在设置静态图片。请勿为图标使用动画图片。

对于打包的扩展程序（从 .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.onClicked 事件。

使用场景

每个标签页的状态

扩展操作在每个标签页中可以处于不同的状态。如需为各个标签页设置值，请使用 action API 设置方法中的 tabId 属性。例如，如需为特定标签页设置徽章文字，请执行类似以下操作：

function getTabId() { /* ... */} function getTabBadge() { /* ... */}  chrome.action.setBadgeText(   {     text: getTabBadge(tabId),     tabId: getTabId(),   },   () => { ... } );

如果省略 tabId 属性，则该设置会被视为全局设置。标签页专用设置优先于全局设置。

启用状态

默认情况下，工具栏操作在每个标签页上均处于启用状态（可点击）。您可以在清单的 action 键中设置 default_state 属性，以更改此默认设置。如果 default_state 设置为 "disabled"，则该操作默认处于停用状态，必须以编程方式启用才能点击。如果 default_state 设置为 "enabled"（默认值），则默认情况下操作处于启用状态且可点击。

您可以使用 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

Chrome 99 及更高版本

属性

windowId

number 可选

要在其中打开操作弹出式窗口的窗口的 ID。如果未指定，则默认为当前活跃窗口。

TabDetails

属性

tabId

number 可选

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

UserSettings

Chrome 91 及更高版本

与扩展程序操作相关的用户指定设置的集合。

属性

isOnToolbar

布尔值

扩展程序的 action 图标是否显示在浏览器窗口的顶级工具栏上（即，用户是否已“固定”该扩展程序）。

UserSettingsChange

Chrome 130 及更高版本

属性

isOnToolbar

布尔值（可选）

扩展程序的 action 图标是否显示在浏览器窗口的顶级工具栏上（即，用户是否已“固定”该扩展程序）。

方法

disable()

chrome.action.disable(
  tabId?: number,
): Promise<void>

停用标签页的操作。

参数

tabId

number 可选

您要修改相应操作的标签页的 ID。

Promise<void>

enable()

chrome.action.enable(
  tabId?: number,
): Promise<void>

为标签页启用操作。默认情况下，操作处于启用状态。

参数

tabId

number 可选

您要修改相应操作的标签页的 ID。

Promise<void>

getBadgeBackgroundColor()

chrome.action.getBadgeBackgroundColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

获取操作的背景颜色。

参数

详细信息

TabDetails

Promise<extensionTypes.ColorArray>

getBadgeText()

chrome.action.getBadgeText(
  details: TabDetails,
): Promise<string>

获取操作的徽章文本。如果未指定任何标签页，则返回非标签页特定的徽章文字。如果启用了 displayActionCountAsBadgeText，则除非存在 declarativeNetRequestFeedback 权限或提供了标签页专用徽章文本，否则系统会返回占位文本。

参数

详细信息

TabDetails

Promise<string>

getBadgeTextColor()

Chrome 110 及更高版本

chrome.action.getBadgeTextColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

获取操作的文字颜色。

参数

详细信息

TabDetails

Promise<extensionTypes.ColorArray>

getPopup()

chrome.action.getPopup(
  details: TabDetails,
): Promise<string>

获取设置为相应操作的弹出式窗口的 HTML 文档。

参数

详细信息

TabDetails

Promise<string>

getTitle()

chrome.action.getTitle(
  details: TabDetails,
): Promise<string>

获取操作的标题。

参数

详细信息

TabDetails

Promise<string>

getUserSettings()

Chrome 91 及更高版本

chrome.action.getUserSettings(): Promise<UserSettings>

返回与扩展程序操作相关的用户指定设置。

Promise<UserSettings>

isEnabled()

Chrome 110 及更高版本

chrome.action.isEnabled(
  tabId?: number,
): Promise<boolean>

指示扩展程序操作是否已针对某个标签页启用（如果未提供 tabId，则表示已全局启用）。仅使用 declarativeContent 启用的操作始终返回 false。

参数

tabId

number 可选

您要检查已启用状态的标签页的 ID。

Promise<boolean>

openPopup()

Chrome 127 及更高版本

chrome.action.openPopup(
  options?: OpenPopupOptions,
): Promise<void>

打开扩展程序的弹出式窗口。在 Chrome 118 和 Chrome 126 之间，此功能仅适用于根据政策安装的扩展程序。

参数

选项

OpenPopupOptions 可选

指定用于打开弹出式窗口的选项。

Promise<void>

setBadgeBackgroundColor()

chrome.action.setBadgeBackgroundColor(
  details: object,
): Promise<void>

设置徽章的背景颜色。

参数

详细信息

对象
- 颜色
  
  字符串 | ColorArray
  
  一个包含四个整数的数组，这些整数的范围为 [0,255]，用于构成徽章的 RGBA 颜色。例如，不透明的红色为 [255, 0, 0, 255]。也可以是具有 CSS 值的字符串，其中不透明的红色为 #FF0000 或 #F00。
- tabId
  
  number 可选
  
  将更改限制为仅在选择特定标签页时生效。在关闭标签页时自动重置。

Promise<void>

setBadgeText()

chrome.action.setBadgeText(
  details: object,
): Promise<void>

为操作设置徽章文本。徽章显示在图标上方。

参数

详细信息

对象
- tabId
  
  number 可选
  
  将更改限制为仅在选择特定标签页时生效。在关闭标签页时自动重置。
- text
  
  字符串（选填）
  
  可以传递任意数量的字符，但空间中只能容纳大约 4 个字符。如果传递的是空字符串 ('')，则会清除标记文本。如果指定了 tabId，但 text 为 null，则指定标签页的文字会被清除，并默认设为全局徽章文字。

Promise<void>

setBadgeTextColor()

Chrome 110 及更高版本

chrome.action.setBadgeTextColor(
  details: object,
): Promise<void>

设置徽章的文字颜色。

参数

详细信息

对象
- 颜色
  
  字符串 | ColorArray
  
  一个包含四个整数的数组，这些整数的范围为 [0,255]，用于构成徽章的 RGBA 颜色。例如，不透明的红色为 [255, 0, 0, 255]。也可以是具有 CSS 值的字符串，其中不透明的红色为 #FF0000 或 #F00。如果不设置此值，系统会自动选择与徽章背景颜色形成对比的颜色，以便显示文字。如果颜色的 Alpha 值相当于 0，则不会设置该颜色，并且会返回错误。
- tabId
  
  number 可选
  
  将更改限制为仅在选择特定标签页时生效。在关闭标签页时自动重置。

Promise<void>

setIcon()

chrome.action.setIcon(
  details: object,
): Promise<void>

为操作设置图标。图标可以指定为图片文件的路径、画布元素的像素数据，也可以指定为包含其中任一信息的字典。必须指定 path 或 imageData 属性。

参数

详细信息

对象
- imageData
  
  ImageData | 对象可选
  
  要设置的图标，可以是 ImageData 对象，也可以是表示图标的字典 {size -> ImageData}。如果图标指定为字典，则会根据屏幕的像素密度选择要使用的实际图片。如果一个屏幕空间单位可容纳的图片像素数为 scale，则系统会选择大小为 scale * n 的图片，其中 n 是界面中图标的大小。必须至少指定一张图片。请注意，“details.imageData = foo”等同于“details.imageData = {'16': foo}”
- 路径
  
  字符串 | 对象可选
  
  相对图片路径或指向要设置的图标的字典 {size -> relative image path}。如果图标指定为字典，则会根据屏幕的像素密度选择要使用的实际图片。如果一个屏幕空间单位可容纳的图片像素数为 scale，则系统会选择大小为 scale * n 的图片，其中 n 是界面中图标的大小。必须至少指定一张图片。请注意，“details.path = foo”等同于“details.path = {'16': foo}”
- tabId
  
  number 可选
  
  将更改限制为仅在选择特定标签页时生效。在关闭标签页时自动重置。

Promise<void>

Chrome 96 及更高版本

setPopup()

chrome.action.setPopup(
  details: object,
): Promise<void>

设置 HTML 文档，以便在用户点击操作的图标时将其作为弹出式窗口打开。

参数

详细信息

对象
- 弹出
  
  字符串
  
  要在弹出式窗口中显示的 HTML 文件的相对路径。如果设置为空字符串 ('')，则不显示任何弹出式窗口。
- tabId
  
  number 可选
  
  将更改限制为仅在选择特定标签页时生效。在关闭标签页时自动重置。

Promise<void>

setTitle()

chrome.action.setTitle(
  details: object,
): Promise<void>

设置操作的标题。此字段会显示在提示中。

参数

详细信息

对象
- tabId
  
  number 可选
  
  将更改限制为仅在选择特定标签页时生效。在关闭标签页时自动重置。
- title
  
  字符串
  
  鼠标悬停时操作应显示的字符串。

Promise<void>

事件

onClicked

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

在用户点击操作图标时触发。如果操作具有弹出式窗口，则不会触发此事件。

参数

callback

函数

callback 参数如下所示：
```
(tab: tabs.Tab) => void
```
- Tab
  
  tabs.Tab

onUserSettingsChanged

Chrome 130 及更高版本

chrome.action.onUserSettingsChanged.addListener(
  callback: function,
)

在与扩展程序操作相关的用户指定设置发生更改时触发。

参数

callback

函数

callback 参数如下所示：
```
(change: UserSettingsChange) => void
```
- 更改
  
  UserSettingsChange

chrome.action 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

说明

可用性

清单

概念和用法

界面组成部分

图标

提示（标题）

徽章

弹出式窗口

使用场景

每个标签页的状态

启用状态

示例

显示弹出式窗口

在点击时注入内容脚本

使用 declarativeContent 模拟操作

类型

OpenPopupOptions

属性

TabDetails

属性

UserSettings

属性

UserSettingsChange

属性

方法

disable()

参数

返回

enable()

参数

返回

getBadgeBackgroundColor()

参数

返回

getBadgeText()

参数

返回

getBadgeTextColor()

参数

返回

getPopup()

参数

返回

getTitle()

参数

返回

getUserSettings()

返回

isEnabled()

参数

返回

openPopup()

参数

返回

setBadgeBackgroundColor()

参数

返回

setBadgeText()

参数

返回

setBadgeTextColor()

参数

返回

setIcon()

参数

返回

setPopup()

参数

返回

setTitle()

参数

返回

事件

onClicked

参数

onUserSettingsChanged

参数

chrome.action