Chrome 现在支持标准化的 browser.* 命名空间（自 Chrome 148 起提供）。我们正在逐步更新文档。如需了解详情，请参阅我们的过渡指南。

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

browser.action

说明

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

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

可用性

Chrome 88 及更高版本 browser.*（自 Chrome 148 起） MV3 及更高版本

清单

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

"action"

如需使用 browser.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" 键也可以设置为包含单个图标路径的字符串，而不是字典。

您还可以调用 action.setIcon()，通过指定其他图片路径或使用 HTML 画布元素（如果通过扩展程序 Service Worker 设置，则使用离屏画布 API）提供动态生成的图标，以编程方式设置扩展程序的图标。

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);
browser.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() 以编程方式进行设置。清单中没有默认徽章设置。徽章颜色值可以是构成徽章 RGBA 颜色的四个介于 0 到 255 之间的整数组成的数组，也可以是包含 CSS 颜色值的字符串。

browser.action.setBadgeBackgroundColor(
  {color: [0, 255, 0, 0]},  // Green
  () => { /* ... */ },
);

browser.action.setBadgeBackgroundColor(
  {color: '#00FF00'},  // Also green
  () => { /* ... */ },
);

browser.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() { /* ... */}

browser.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
browser.action.onClicked.addListener((tab) => {
  browser.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
browser.runtime.onInstalled.addListener(() => {
  // Page actions are disabled by default and enabled on select tabs
  browser.action.disable();

  // Clear all rules to ensure only our expected rules are set
  browser.declarativeContent.onPageChanged.removeRules(undefined, () => {
    // Declare a rule to enable the action on example.com pages
    let exampleRule = {
      conditions: [
        new browser.declarativeContent.PageStateMatcher({
          pageUrl: {hostSuffix: '.example.com'},
        })
      ],
      actions: [new browser.declarativeContent.ShowAction()],
    };

    // Finally, apply our new array of rules
    let rules = [exampleRule];
    browser.declarativeContent.onPageChanged.addRules(rules);
  });
});

类型

OpenPopupOptions

Chrome 99 及更高版本 browser.*（自 Chrome 148 起）

属性

windowId

number 可选

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

TabDetails

属性

tabId

number 可选

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

UserSettings

Chrome 91 及更高版本 browser.*（自 Chrome 148 起）

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

属性

isOnToolbar

布尔值

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

UserSettingsChange

Chrome 130 及更高版本 browser.*（自 Chrome 148 起）

属性

isOnToolbar

布尔值（可选）

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

方法

disable()

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

停用标签页的操作。

参数

tabId

number 可选

要修改其操作的标签页的 ID。

承诺<void>

enable()

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

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

参数

tabId

number 可选

要修改其操作的标签页的 ID。

承诺<void>

getBadgeBackgroundColor()

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

获取操作的背景颜色。

参数

详细信息

TabDetails

Promise<extensionTypes.ColorArray>

getBadgeText()

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

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

参数

详细信息

TabDetails

Promise<string>

getBadgeTextColor()

Chrome 110+ browser.*（自 Chrome 148 起）

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

获取操作的文本颜色。

参数

详细信息

TabDetails

Promise<extensionTypes.ColorArray>

getPopup()

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

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

参数

详细信息

TabDetails

Promise<string>

getTitle()

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

获取操作的标题。

参数

详细信息

TabDetails

Promise<string>

getUserSettings()

Chrome 91 及更高版本 browser.*（自 Chrome 148 起）

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

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

Promise<UserSettings>

isEnabled()

Chrome 110+ browser.*（自 Chrome 148 起）

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

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

参数

tabId

number 可选

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

Promise<boolean>

openPopup()

Chrome 127 及更高版本 browser.*（自 Chrome 148 起）

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

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

参数

选项

OpenPopupOptions 可选

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

承诺<void>

setBadgeBackgroundColor()

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

设置徽章的背景颜色。

参数

详细信息

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

承诺<void>

setBadgeText()

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

设置操作的标志文字。该标记会显示在图标顶部。

参数

详细信息

对象
- tabId
  
  number 可选
  
  仅在选择特定标签页时应用更改。在标签页关闭时自动重置。
- text
  
  字符串可选
  
  您可以传递任意数量的字符，但该空间只能容纳大约四个字符。如果传递空字符串 ('')，则会清除标记文本。如果指定了 tabId，但 text 为 null，则指定标签页的文本会被清除，并默认设为全局标志文本。

承诺<void>

setBadgeTextColor()

Chrome 110+ browser.*（自 Chrome 148 起）

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

设置徽章的文字颜色。

参数

详细信息

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

承诺<void>

setIcon()

browser.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 可选
  
  仅在选择特定标签页时应用更改。在标签页关闭时自动重置。

承诺<void>

Chrome 96 及更高版本 browser.*（自 Chrome 148 起）

setPopup()

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

设置当用户点击操作图标时，要作为弹出式窗口打开的 HTML 文档。

参数

详细信息

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

承诺<void>

setTitle()

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

设置操作的标题。此信息会显示在提示中。

参数

详细信息

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

承诺<void>

事件

onClicked

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

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

参数

callback

函数

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

onUserSettingsChanged

Chrome 130 及更高版本 browser.*（自 Chrome 148 起）

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

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

参数

callback

函数

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

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

说明

可用性

清单

概念和用法

界面组成部分

图标

提示（标题）

徽章

弹出式窗口

使用场景

每个标签页的状态

启用状态

示例

显示弹出式窗口

点击时注入内容脚本

使用 declarativeContent 模拟操作

类型

OpenPopupOptions

属性

TabDetails

属性

UserSettings

属性

UserSettingsChange

属性

方法

disable()

参数

返回

enable()

参数

返回

getBadgeBackgroundColor()

参数

返回

getBadgeText()

参数

返回

getBadgeTextColor()

参数

返回

getPopup()

参数

返回

getTitle()

参数

返回

getUserSettings()

返回

isEnabled()

参数

返回

openPopup()

参数

返回

setBadgeBackgroundColor()

参数

返回

setBadgeText()

参数

返回

setBadgeTextColor()

参数

返回

setIcon()

参数

返回

setPopup()

参数

返回

setTitle()

参数

返回

事件

onClicked

参数

onUserSettingsChanged

参数

browser.action