chrome.action

说明

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

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

可用性

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" 键。

概念和用法

界面的各个部分

图标

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

"default_icon" 键是映像路径大小字典。Chrome 会使用这些图标 选择要使用的图片比例。如果未找到完全匹配项，Chrome 会选择最接近的匹配项 并将其调整为适合图片的大小，这可能会影响图片质量。

因为 1.5 倍或 1.2 倍等不太常见的缩放比例 我们建议您提供多种尺寸的图标。这也 可以确保您的扩展程序不会因图标显示尺寸发生改变而未来变化。不过， 如果只提供一个尺寸，则 "default_icon" 键也可设置为 字符串替换为指向单个图标（而非字典）的路径。

您还可以调用 action.setIcon()，以编程方式设置扩展程序的图标 方法是指定不同的图片路径或使用 HTML 画布提供动态生成的图标 元素，或者，如果设置来自扩展程序 Service Worker，则屏幕外 canvas 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);
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 之间的四个整数，这些整数构成 标记或包含 CSS color 值的字符串。

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 像素之间。

弹出式窗口最初由 "action" 键中的 "default_popup" 属性设置， manifest.json 文件。此属性应指向扩展程序中的相对路径（如果存在） 目录。您也可以使用 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 中的 chrome-extension-samples 存储库

显示弹出式窗口

当用户点击某个扩展程序的操作时，该扩展程序通常会显示一个弹出式窗口。接收者 在您自己的扩展程序中实现这一点，在 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

    编号（选填）

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

TabDetails

属性

  • tabId

    编号（选填）

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

UserSettings

Chrome 91 及更高版本

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

属性

  • isOnToolbar

    布尔值

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

UserSettingsChange

待处理

属性

  • isOnToolbar

    布尔值（可选）

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

方法

disable()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.action.disable(
  tabId?: number,
  callback?: function,
)

对标签页停用操作。

参数

  • tabId

    编号（选填）

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

enable()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.action.enable(
  tabId?: number,
  callback?: function,
)

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

参数

  • tabId

    编号（选填）

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

getBadgeBackgroundColor()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.action.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

获取操作的背景颜色。

参数

返回

  • Promise&lt;browserAction.ColorArray&gt;

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

getBadgeText()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.action.getBadgeText(
  details: TabDetails,
  callback?: function,
)

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

参数

  • 详细信息

    TabDetails

  • callback

    函数（可选）

    callback 参数如下所示： 

    (result: string) => void

    • 结果

      字符串

返回

  • 承诺<字符串>

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

getBadgeTextColor()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 110 及更高版本 
chrome.action.getBadgeTextColor(
  details: TabDetails,
  callback?: function,
)

获取操作的文本颜色。

参数

返回

  • Promise&lt;browserAction.ColorArray&gt;

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

getPopup()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.action.getPopup(
  details: TabDetails,
  callback?: function,
)

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

参数

  • 详细信息

    TabDetails

  • callback

    函数（可选）

    callback 参数如下所示： 

    (result: string) => void

    • 结果

      字符串

返回

  • 承诺<字符串>

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

getTitle()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.action.getTitle(
  details: TabDetails,
  callback?: function,
)

获取操作的标题。

参数

  • 详细信息

    TabDetails

  • callback

    函数（可选）

    callback 参数如下所示： 

    (result: string) => void

    • 结果

      字符串

返回

  • 承诺<字符串>

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

getUserSettings()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 91 及更高版本 
chrome.action.getUserSettings(
  callback?: function,
)

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

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    (userSettings: UserSettings) => void

返回

  • Promise&lt;UserSettings&gt;

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

isEnabled()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 110 及更高版本 
chrome.action.isEnabled(
  tabId?: number,
  callback?: function,
)

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

参数

  • tabId

    编号（选填）

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    (isEnabled: boolean) => void

    • isEnabled

      布尔值

      如果扩展程序操作已启用，则为“true”。

返回

  • Promise&lt;boolean&gt;

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

openPopup()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 127 及更高版本 
chrome.action.openPopup(
  options?: OpenPopupOptions,
  callback?: function,
)

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

参数

  • 选项

    OpenPopupOptions 可选

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

setBadgeBackgroundColor()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.action.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

设置标志的背景颜色。

参数

  • 详细信息

    对象

    • 颜色

      string |ColorArray

      由 [0,255] 范围内的四个整数组成的数组，这些整数构成标志的 RGBA 颜色。例如，不透明红色为 [255, 0, 0, 255]。也可以是包含 CSS 值的字符串，其中不透明红色为 #FF0000 或 #F00。

    • tabId

      编号（选填）

      将更改限制在选择特定标签页时。在标签页关闭后自动重置。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

setBadgeText()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.action.setBadgeText(
  details: object,
  callback?: function,
)

设置操作的标志文本。标记显示在图标上。

参数

  • 详细信息

    对象

    • tabId

      编号（选填）

      将更改限制在选择特定标签页时。在标签页关闭后自动重置。

    • text

      字符串（可选）

      可以传递任意数量的字符，但空格中只能传递大约 4 个字符。如果传递了空字符串 ('')，则标记文本会被清除。如果指定了 tabId 且 text 为 null，则系统会清除指定标签页的文本，并默认显示全局标志文本。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

setBadgeTextColor()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 110 及更高版本 
chrome.action.setBadgeTextColor(
  details: object,
  callback?: function,
)

设置标志的文本颜色。

参数

  • 详细信息

    对象

    • 颜色

      string |ColorArray

      由 [0,255] 范围内的四个整数组成的数组，这些整数构成标志的 RGBA 颜色。例如，不透明红色为 [255, 0, 0, 255]。也可以是包含 CSS 值的字符串，其中不透明红色为 #FF0000 或 #F00。如果未设置此值，系统会自动选择与徽章的背景颜色形成鲜明对比的颜色，使文本清晰可见。系统不会设置 alpha 值等于 0 的颜色，并会返回错误。

    • tabId

      编号（选填）

      将更改限制在选择特定标签页时。在标签页关闭后自动重置。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

setIcon()

<ph type="x-smartling-placeholder"></ph> 承诺 
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}'

    • 路径

      string |对象（可选）

      相对图片路径或字典 {size ->指向要设置的图标的相对图像路径}。如果将图标指定为字典，则系统会根据屏幕的像素密度选择要使用的实际图片。如果适合一个屏幕空间单元的图片像素数等于 scale，则系统将选择尺寸为 scale * n 的图片，其中 n 是界面中图标的尺寸。必须至少指定一张图片。请注意，“details.path = foo”等同于 'details.path = {'16': foo}'

    • tabId

      编号（选填）

      将更改限制在选择特定标签页时。在标签页关闭后自动重置。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 96 及更高版本

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

setPopup()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.action.setPopup(
  details: object,
  callback?: function,
)

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

参数

  • 详细信息

    对象

    • 弹出

      字符串

      要在弹出式窗口中显示的 HTML 文件的相对路径。如果设置为空字符串 ('')，则不会显示弹出式窗口。

    • tabId

      编号（选填）

      将更改限制在选择特定标签页时。在标签页关闭后自动重置。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

setTitle()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.action.setTitle(
  details: object,
  callback?: function,
)

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

参数

  • 详细信息

    对象

    • tabId

      编号（选填）

      将更改限制在选择特定标签页时。在标签页关闭后自动重置。

    • 标题

      字符串

      鼠标悬停时操作应显示的字符串。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

事件

onClicked

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

    (tab: tabs.Tab) => void

onUserSettingsChanged

待处理
chrome.action.onUserSettingsChanged.addListener(
  callback: function,
)

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

参数