chrome.pageAction

说明

使用 chrome.pageAction API 将图标放置在 Google Chrome 主工具栏中，位于地址栏的右侧。网页操作表示可在当前网页上进行，但不适用于所有网页的操作。网页操作在闲置时会显示为灰色。

可用性

≤ MV2

一些示例：

• 订阅此页面的 RSS Feed
• 利用此页面的照片制作幻灯片

以下屏幕截图中的 RSS 图标表示一项网页操作，可让您订阅当前网页的 RSS Feed。

隐藏的页面操作呈灰显状态。例如，下面的 RSS Feed 会灰显，因为您无法订阅当前页面的 Feed：

请考虑改用浏览器操作，以便用户始终能与您的扩展程序互动。

清单

在扩展程序清单中注册您的页面操作，如下所示：

{
  "name": "My extension",
  ...
  "page_action": {
    "default_icon": {                    // optional
      "16": "images/icon16.png",           // optional
      "24": "images/icon24.png",           // optional
      "32": "images/icon32.png"            // optional
    },
    "default_title": "Google Mail",      // optional; shown in tooltip
    "default_popup": "popup.html"        // optional
  },
  ...
}

由于缩放比例不那么常见的设备（如 1.5 倍或 1.2 倍）越来越常见，因此我们建议您提供多种尺寸的图标。Chrome 会选择最近的一个并对其进行缩放，以填充 16 dip 空间。这还可确保，如果图标显示大小发生变化，您无需执行任何其他操作即可提供不同的图标！但是，如果大小差异过大，这种缩放可能会导致图标丢失细节或看起来模糊不清。

我们仍支持用于注册默认图标的旧语法：

{
  "name": "My extension",
  ...
  "page_action": {
    ...
    "default_icon": "images/icon32.png"  // optional
    // equivalent to "default_icon": { "32": "images/icon32.png" }
  },
  ...
}

界面的各个部分

与浏览器操作一样，页面操作也可以具有图标、提示和弹出式窗口；但它们不能有标记。此外，网页操作可能会灰显。您可以参阅浏览器操作界面，了解有关图标、提示和弹出式窗口的信息。

您可以分别使用 pageAction.show 和 pageAction.hide 方法使网页操作显示和灰显。默认情况下，网页操作会显示为灰色。显示图标时，您可以指定应在其中显示该图标的标签页。该图标会一直显示，直到该标签页关闭或开始显示其他网址（例如，因为用户点击了链接）。

提示

为了获得最佳视觉冲击效果，请遵循以下准则：

• 务必对仅适用于少数网页的功能使用网页操作。
• 请勿对适合大多数网页的功能使用网页操作。请改用浏览器操作。
• 请勿持续为图标添加动画效果。真是太烦了。

类型

ImageDataType

图片的像素数据。必须是 ImageData 对象（例如，来自 canvas 元素中）。

类型

ImageData

TabDetails

Chrome 88 及更高版本

属性

• tabId

  数字可选

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

方法

getPopup()

Promise

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

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

参数

• 明细

  TabDetails

• callback

  函数（可选）

  callback 参数如下所示：

  (result: string)=>void

  • 结果

    string

返回

• Promise<string>

  Chrome 101 及更高版本

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

getTitle()

Promise

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

获取网页操作的标题。

参数

• 明细

  TabDetails

• callback

  函数（可选）

  callback 参数如下所示：

  (result: string)=>void

  • 结果

    string

返回

• Promise<string>

  Chrome 101 及更高版本

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

hide()

Promise

chrome.pageAction.hide(
  tabId: number,
  callback?: function,
)

隐藏网页操作。隐藏的页面操作仍会显示在 Chrome 工具栏中，但会灰显。

参数

• tabId

  number

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

• callback

  函数（可选）

  Chrome 67 及更高版本

  callback 参数如下所示：

  ()=>void

返回

• Promise<void>

  Chrome 101 及更高版本

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

setIcon()

Promise

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

设置网页操作的图标。可将图标指定为图像文件的路径或画布元素的像素数据，或者指定这些图标的字典。必须指定 path 或 imageData 属性。

参数

• 明细

  对象

  • iconIndex

    数字可选

    已弃用。系统会忽略此参数。

  • 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

    number

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

• callback

  函数（可选）

  callback 参数如下所示：

  ()=>void

返回

• Promise<void>

  Chrome 101 及更高版本

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

setPopup()

Promise

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

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

参数

• 明细

  对象

  • 弹出式内容（窗口/广告/etc.）

    string

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

  • tabId

    number

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

• callback

  函数（可选）

  Chrome 67 及更高版本

  callback 参数如下所示：

  ()=>void

返回

• Promise<void>

  Chrome 101 及更高版本

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

setTitle()

Promise

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

设置网页操作的标题。这会显示在网页操作上方的提示中。

参数

• 明细

  对象

  • tabId

    number

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

  • title

    string

    提示字符串。

• callback

  函数（可选）

  Chrome 67 及更高版本

  callback 参数如下所示：

  ()=>void

返回

• Promise<void>

  Chrome 101 及更高版本

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

show()

Promise

chrome.pageAction.show(
  tabId: number,
  callback?: function,
)

显示网页操作。每当选中该标签页时，系统都会显示网页操作。

参数

• tabId

  number

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

• callback

  函数（可选）

  Chrome 67 及更高版本

  callback 参数如下所示：

  ()=>void

返回

• Promise<void>

  Chrome 101 及更高版本

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

活动

onClicked

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

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

参数

• callback

  功能

  callback 参数如下所示：

  (tab: tabs.Tab)=>void

  • 标签页

    tabs.Tab