chrome.action

Description

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

Manifest Keys

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

Availability(可用性)

Chrome 88+ MV3+

您可以使用 chrome.action API 在 Chrome 的 UI 中控制扩展程序的工具栏按钮。操作图标显示在浏览器工具栏中，位于多功能框的右侧（在从左到右的设备上）。安装后，默认情况下，这些会出现在扩展菜单（拼图）中。用户可以选择将您的扩展图标固定到工具栏。

请注意，即使未指定action key，每个扩展程序在 Chrome 的工具栏中都会有一个图标。

# Manifest

为了使用 chrome.action API，您需要将“manifest_version”指定为 3 或更高，并在manifest文件中包含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
  },
  ...
}

这些值中的每一个都是可选的；技术上允许使用空字典。

这些属性将在下面详细描述。

# 用户界面的组成部分

# Icon

图标是工具栏按钮中使用的主要图像。图标有 16 个 DIP（独立于设备的像素）宽和高。该图标最初由manifest.json 文件中action条目中的 default_icon 键设置。此键是图像路径大小的字典。 Chrome 将使用这些图标来选择要使用的图像比例。如果未找到完全匹配，Chrome 将选择最接近的可用图像并将其缩放以适合图像。但是，这种缩放会导致图标丢失细节或看起来模糊。

由于具有 1.5x 或 1.2x 等不太常见比例因子的设备变得越来越普遍，因此我们鼓励您为图标提供多种尺寸。这也确保了如果图标显示大小发生变化，您无需再做任何工作来提供不同的图标。

也可以使用 action.setIcon() 方法以编程方式设置图标。这可用于指定不同的图像路径或使用 HTML canvas element提供动态生成的图标，或者，如果从扩展服务工作者(service worker)设置，则为屏幕外画布(offscreen 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}, () => { /* ... */ });

action.setIcon() API 旨在设置静态图像。它不应该用于模拟动画。

# Formats

对于打包扩展（从 .crx 文件安装），图像可以采用 Blink 渲染引擎可以显示的大多数格式，包括 PNG、JPEG、BMP、ICO 等（不支持 SVG）。解压后的扩展必须使用 PNG 格式的图像。

# 工具提示（标题）(Tooltip (title))

当用户将鼠标悬停在工具栏中的扩展图标上时，会出现工具提示或标题。当按钮获得焦点时，它也包含在屏幕阅读器朗读的可访问文本中。

默认工具提示是从 manifest.json 中action对象的 default_title 字段设置的。您还可以使用 action.setTitle() 方法以编程方式设置它。

# Badge(标识)

操作(Actions)可以选择显示“badge”——在图标上分层的一些文本。这使得更新操作以显示有关扩展状态的少量信息变得容易，比如柜台。标识(badge)具有文本组件和背景颜色。

请注意，标识(badge)的空间有限，通常应使用四个或更少的字符。

标识(badge)没有从清单(manifest)中获取的默认值；您可以使用 action.setBadgeBackgroundColor() 和 action.setBadgeText() 以编程方式设置它。设置颜色时，这些值可以是组成标识(badge)的 RGBA 颜色的 0 到 255 之间的四个整数的数组，也可以是具有 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 事件。

# Per-tab state(每个标签状态)

每个选项卡的扩展操作可以有不同的状态。例如，您可以将每个选项卡上的标识（badge）文本设置为不同（以显示特定于选项卡的状态）。您可以在action API 的各种设置方法中使用 tabId 属性设置单个选项卡的值。例如，要在特定选项卡上设置标识(badge)文本，您可以执行以下操作：

function getTabId() { /* ... */}
function getTabBadge() { /* ... */}

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

如果省略 tabId 属性，则该设置将被视为全局设置。特定于选项卡的设置优先于任何全局设置。

# Enabled state(启用状态)

默认情况下，在每个选项卡上启用（可单击）工具栏操作。您可以使用 action.enable() 和 action.disable() 方法来控制它。这仅影响是否将弹出窗口（如果有）或 action.onClicked 事件分派到您的扩展程序；它不会影响操作(action)在工具栏中的存在。

# Examples(例子)

以下示例显示了在扩展中使用操作的一些常见方式。如需更强大的操作功能演示，请参阅 chrome-extension-samples 存储库中的 Action API 示例。

# Show a popup(显示弹窗)

当用户单击扩展程序的操作时，扩展程序通常会显示弹出窗口。要在您自己的扩展程序中实现此功能，请在 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>

# 单击时注入内容脚本(Injecting a content script on click)

扩展的常见模式是使用扩展的操作公开其主要功能。下面的示例演示了这种模式。当用户单击操作时，扩展程序会将内容脚本注入当前页面。然后内容脚本会显示警报以验证一切是否按预期工作。

// 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 模拟 pageActions

chrome.action API 替换了 Manifest V3 中的 browserAction 和 pageAction API。默认情况下，动作类似于浏览器动作，但可以使用action API 模拟页面动作的行为。

此示例显示扩展程序的后台逻辑如何 (a) 默认情况下禁用操作(action)和 (b) 使用 declarativeContent 在特定站点上启用操作。

// background.js

// 包装在 onInstalled 回调中以避免不必要的工作
// 每次后台脚本运行时
chrome.runtime.onInstalled.addListener(() => {
  // 默认情况下禁用页面操作并在选择选项卡上启用
  chrome.action.disable();

  // 清除所有规则以确保只设置我们预期的规则
  chrome.declarativeContent.onPageChanged.removeRules(undefined, () => {
    // 声明一个规则来启用 example.com 页面上的操作
    let exampleRule = {
      conditions: [
        new chrome.declarativeContent.PageStateMatcher({
          pageUrl: {hostSuffix: '.example.com'},
        })
      ],
      actions: [new chrome.declarativeContent.ShowAction()],
    };

    // 最后，应用我们的新规则数组
    let rules = [exampleRule];
    chrome.declarativeContent.onPageChanged.addRules(rules);
  });
});

Summary

Types
TabDetails
UserSettings
Methods
disable
enable
getBadgeBackgroundColor
getBadgeText
getPopup
getTitle
getUserSettings
setBadgeBackgroundColor
setBadgeText
setIcon
setPopup
setTitle
Events
onClicked

Types

TabDetails

PROPERTIES

tabId
number optional
要查询状态的选项卡的 ID。如果未指定选项卡，则返回非选项卡特定的状态。

UserSettings

Chrome 91+

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

PROPERTIES

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

Methods

disable

chrome.action.disable(
  tabId?: number,
  callback?: function,
)

Promise

禁用选项卡的操作。

PARAMETERS

tabId
number optional
要为其修改操作的选项卡的 ID。
callback
function optional
The callback parameter looks like:
```
() => void
```

RETURNS

Promise<void>
Pending
这仅在未指定回调参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与回调的第一个参数相同。

enable

chrome.action.enable(
  tabId?: number,
  callback?: function,
)

Promise

启用选项卡的操作。默认情况下，启用操作。

PARAMETERS

tabId
number optional
要为其修改操作的选项卡的 ID。
callback
function optional
The callback parameter looks like:
```
() => void
```

RETURNS

Promise<void>
Pending
这仅在未指定回调参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与回调的第一个参数相同。

getBadgeBackgroundColor

chrome.action.getBadgeBackgroundColor( details: TabDetails, callback?: function, )

Promise

获取动作的背景颜色。

PARAMETERS

details
TabDetails
callback
function optional
The callback parameter looks like:
(result: ColorArray) => void
- result
  ColorArray

RETURNS

Promise<browserAction.ColorArray>
Pending
这仅在未指定回调参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与回调的第一个参数相同。

getBadgeText

chrome.action.getBadgeText( details: TabDetails, callback?: function, )

Promise

获取操作的徽章文本。如果未指定选项卡，则返回非选项卡特定的标记文本。如果 displayActionCountAsBadgeText 已启用，除非存在 declarativeNetRequestFeedback 权限或提供了特定于选项卡的徽章文本，否则将返回占位符文本。

PARAMETERS

details
TabDetails
callback
function optional
The callback parameter looks like:
```
(result: string) => void
```
- result
  string

RETURNS

Promise<string>
Pending
这仅在未指定回调参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与回调的第一个参数相同。

getPopup

chrome.action.getPopup( details: TabDetails, callback?: function, )

Promise

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

PARAMETERS

details
TabDetails
callback
function optional
The callback parameter looks like:
```
(result: string) => void
```
- result
  string

RETURNS

Promise<string>
Pending
这仅在未指定回调参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与回调的第一个参数相同。

getTitle

chrome.action.getTitle( details: TabDetails, callback?: function, )

Promise

获取动作的标题。

PARAMETERS

details
TabDetails
callback
function optional
The callback parameter looks like:
```
(result: string) => void
```
- result
  string

RETURNS

Promise<string>
Pending
这仅在未指定回调参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与回调的第一个参数相同。

getUserSettings

chrome.action.getUserSettings(
  callback?: function,
)

Promise Chrome 91+

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

PARAMETERS

callback
function optional
The callback parameter looks like:
(userSettings: UserSettings) => void
- userSettings
  UserSettings

RETURNS

Promise<UserSettings>
Pending
这仅在未指定回调参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与回调的第一个参数相同。

setBadgeBackgroundColor

chrome.action.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

Promise

设置徽章的背景颜色。

PARAMETERS

details
object
- color
  string | ColorArray
  [0,255] 范围内的四个整数组成的数组，构成徽章的 RGBA 颜色。例如，不透明的红色是 [255, 0, 0, 255]。也可以是带有 CSS 值的字符串，不透明的红色是 #FF0000 或 #F00。
- tabId
  number optional
  将更改限制在选择特定选项卡时。选项卡关闭时自动重置。

callback
function optional
The callback parameter looks like:
```
() => void
```

RETURNS

Promise<void>
Pending
这仅在未指定回调参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与回调的第一个参数相同。

setBadgeText

chrome.action.setBadgeText(
  details: object,
  callback?: function,
)

Promise

设置动作的标记文本。徽章显示在图标的顶部。

PARAMETERS

details
object
- tabId
  number optional
  将更改限制在选择特定选项卡时。选项卡关闭时自动重置。
- text
  string
  可以传递任意数量的字符，但空间中只能容纳大约四个字符。

callback
function optional
The callback parameter looks like:
```
() => void
```

RETURNS

Promise<void>
Pending
这仅在未指定回调参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与回调的第一个参数相同。

setIcon

chrome.action.setIcon(
  details: object,
  callback?: function,
)

Promise

设置动作的图标。图标可以指定为图像文件的路径或来自画布元素的像素数据，或作为其中之一的字典。必须指定路径或 imageData 属性。

PARAMETERS

details
object
- imageData
  ImageData | object optional
  ImageData 对象或字典 {size -> ImageData} 表示要设置的图标。如果将图标指定为字典，则根据屏幕的像素密度选择要使用的实际图像。如果适合一个屏幕空间单位的图像像素数等于 scale，则将选择 size scale * n 的图像，其中 n 是 UI 中图标的大小。必须至少指定一张图片。请注意，'details.imageData = foo' 等价于 'details.imageData = {'16': foo}'
- path
  string | object optional
  指向要设置的图标的相对图像路径或字典 {size -> relative image path}。如果将图标指定为字典，则根据屏幕的像素密度选择要使用的实际图像。如果适合一个屏幕空间单位的图像像素数等于 scale，则将选择 size scale * n 的图像，其中 n 是 UI 中图标的大小。必须至少指定一张图片。请注意，'details.path = foo' 等价于 'details.path = {'16': foo}'
- tabId
  number optional
  将更改限制在选择特定选项卡时。选项卡关闭时自动重置。

callback
function optional
The callback parameter looks like:
```
() => void
```

RETURNS

Promise<void>
Pending
这仅在未指定回调参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与回调的第一个参数相同。

setPopup

chrome.action.setPopup(
  details: object,
  callback?: function,
)

Promise

设置 HTML 文档在用户单击操作图标时作为弹出窗口打开。

PARAMETERS

details
object
- popup
  string
  要在弹出窗口中显示的 HTML 文件的相对路径。如果设置为空字符串 ('')，则不显示弹出窗口。
- tabId
  number optional
  将更改限制在选择特定选项卡时。选项卡关闭时自动重置。

callback
function optional
The callback parameter looks like:
```
() => void
```

RETURNS

Promise<void>
Pending
这仅在未指定回调参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与回调的第一个参数相同。

setTitle

chrome.action.setTitle(
  details: object,
  callback?: function,
)

Promise

设置动作的标题。这显示在工具提示中。

PARAMETERS

details
object
- tabId
  number optional
  将更改限制在选择特定选项卡时。选项卡关闭时自动重置。
- title
  string
  鼠标悬停时动作应显示的字符串。

callback
function optional
The callback parameter looks like:
```
() => void
```

RETURNS

Promise<void>
Pending
这仅在未指定回调参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与回调的第一个参数相同。

Events

onClicked

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

单击操作图标时触发。如果操作有弹出窗口，则不会触发此事件。

PARAMETERS

callback
function
The callback parameter looks like:
(tab: tabs.Tab) => void
- tab
  tabs.Tab

By.一粒技术服务

chrome.action

Description

Manifest Keys

Availability(可用性)

# Manifest

# 用户界面的组成部分

# Icon

# Formats

# 工具提示（标题）(Tooltip (title))

# Badge(标识)

# Popup

# Per-tab state(每个标签状态)

# Enabled state(启用状态)

# Examples(例子)

# Show a popup(显示弹窗)

# 单击时注入内容脚本(Injecting a content script on click)

# 使用 declarativeContent 模拟 pageActions

Summary

Types

TabDetails

PROPERTIES

UserSettings

PROPERTIES

Methods

disable

PARAMETERS

RETURNS

enable

PARAMETERS

RETURNS

getBadgeBackgroundColor

PARAMETERS

RETURNS

getBadgeText

PARAMETERS

RETURNS

getPopup

PARAMETERS

RETURNS

getTitle

PARAMETERS

RETURNS

getUserSettings

PARAMETERS

RETURNS

setBadgeBackgroundColor

PARAMETERS

RETURNS

setBadgeText

PARAMETERS

RETURNS

setIcon

PARAMETERS

RETURNS

setPopup

PARAMETERS

RETURNS

setTitle

PARAMETERS

RETURNS

Events

onClicked

PARAMETERS

results matching ""

No results matching ""