chrome.pageAction

说明

使用 chrome.pageAction API 将图标放置在 Google Chrome 主工具栏(地址栏右侧)中。网页操作是指可对当前网页执行,但并不适用于所有网页的操作。处于非活动状态的页面操作会显示为灰色。

可用性

<ph type="x-smartling-placeholder"></ph> &amp;leq;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.showpageAction.hide 方法。默认情况下,网页操作会显示为灰色。当您 您可以指定在哪个标签显示图标。该图标会一直显示,直到出现该标签页 关闭或开始显示其他网址(例如,由于用户点击链接)。

提示

为了获得最佳的视觉冲击力,请遵循以下准则:

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

类型

ImageDataType

图片的像素数据。必须是 ImageData 对象(例如,来自 canvas 元素)。

类型

ImageData

TabDetails

Chrome 88 及更高版本

属性

  • tabId

    编号(选填

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

方法

getPopup()

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

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

参数

  • 详细信息
  • callback

    函数(可选)

    callback 参数如下所示:

    (result: string) => void

    • 结果

      字符串

返回

  • 承诺<字符串>

    Chrome 浏览器 101 及以上版本

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

getTitle()

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

获取页面操作的标题。

参数

  • 详细信息
  • callback

    函数(可选)

    callback 参数如下所示:

    (result: string) => void

    • 结果

      字符串

返回

  • 承诺<字符串>

    Chrome 浏览器 101 及以上版本

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

hide()

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

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

参数

  • tabId

    number

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

  • callback

    函数(可选)

    Chrome 67 及更高版本

    callback 参数如下所示:

    () => void

返回

  • 承诺<void>

    Chrome 浏览器 101 及以上版本

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

setIcon()

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

设置页面操作的图标。可以将图标指定为图像文件的路径、画布元素中的像素数据,或者其中一个的字典。必须指定 pathimageData 属性。

参数

  • 详细信息

    对象

    • iconIndex

      编号(选填

      已弃用。此参数会被忽略。

    • 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

      number

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

  • callback

    函数(可选)

    callback 参数如下所示:

    () => void

返回

  • 承诺<void>

    Chrome 浏览器 101 及以上版本

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

setPopup()

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

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

参数

  • 详细信息

    对象

    • 弹出

      字符串

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

    • tabId

      number

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

  • callback

    函数(可选)

    Chrome 67 及更高版本

    callback 参数如下所示:

    () => void

返回

  • 承诺<void>

    Chrome 浏览器 101 及以上版本

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

setTitle()

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

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

参数

  • 详细信息

    对象

    • tabId

      number

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

    • 标题

      字符串

      提示字符串。

  • callback

    函数(可选)

    Chrome 67 及更高版本

    callback 参数如下所示:

    () => void

返回

  • 承诺<void>

    Chrome 浏览器 101 及以上版本

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

show()

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

显示网页操作。每次选择标签页时都会显示网页操作。

参数

  • tabId

    number

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

  • callback

    函数(可选)

    Chrome 67 及更高版本

    callback 参数如下所示:

    () => void

返回

  • 承诺<void>

    Chrome 浏览器 101 及以上版本

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

事件

onClicked

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

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

参数

  • callback

    函数

    callback 参数如下所示:

    (tab: tabs.Tab) => void