browser.contextMenus

说明

使用 chrome.contextMenus API 向 Google Chrome 的上下文菜单添加内容。您可以选择要将添加的上下文菜单项应用于哪些类型的对象，例如图片、超链接和网页。

权限

contextMenus

您必须在扩展程序的清单中声明 "contextMenus" 权限，才能使用该 API。此外，您还应指定一个 16x16 像素的图标，以便在菜单项旁边显示。例如：

{
  "name": "My extension",
  ...
  "permissions": [
    "contextMenus"
  ],
  "icons": {
    "16": "icon-bitty.png",
    "48": "icon-small.png",
    "128": "icon-large.png"
  },
  ...
}

概念和用法

上下文菜单项可以出现在任何文档（或文档中的框架）中，即使是具有 file:// 或 chrome:// 网址的文档。如需控制您的项可以出现在哪些文档中，请在调用 create() 或 update() 方法时指定 documentUrlPatterns 字段。

您可以根据需要创建任意数量的上下文菜单项，但如果您的扩展程序中有多个菜单项同时可见，Google Chrome 会自动将它们收起为一个父级菜单。

本页面的大部分内容都包含此 API 成员的参考信息。 如需了解如何使用该 API，请参阅构建上下文菜单。

示例

如需试用此 API，请从 chrome-extension-samples 代码库中安装 contextMenus API 示例。

类型

ContextType

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

菜单可能出现的不同情境。指定“all”相当于除“launcher”和“tab”之外的所有其他上下文的组合。“launcher”上下文仅受应用支持，用于向点击启动器/任务栏/程序坞等中的应用图标时显示的上下文菜单添加菜单项。不同的平台可能会对启动器上下文菜单中实际支持的内容施加限制。

枚举

"all"

"page"

"frame"

"selection"

"link"

"editable"

"image"

"video"

"audio"

"launcher"

"action"
适用于扩展程序操作（其工具栏图标）的上下文菜单。

"tab"
适用于标签栏中标签页的上下文菜单。

CreateProperties

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

新上下文菜单项的属性。

属性

  • 已勾选

    布尔值 （可选）

    复选框或单选按钮的初始状态：true 表示已选中，false 表示未选中。在给定组中，一次只能选择一个单选按钮。

  • contexts

    [ContextType, …ContextType[]] 可选

    此菜单项将出现的上下文列表。默认为 ['page']。

  • documentUrlPatterns

    string[] 可选

    限制该项仅应用于网址与给定格式之一匹配的文档或框架。如需详细了解格式，请参阅匹配格式。

  • 已启用

    布尔值 （可选）

    此上下文菜单项处于启用还是停用状态。默认为 true。

  • id

    字符串 可选

    要为此商品分配的唯一 ID。对于活动页面，此属性为必填属性。不能与此附加信息的其他 ID 相同。

  • parentId

    字符串 | 数值可选

    父级菜单项的 ID；这会使该项成为之前添加的项的子项。

  • targetUrlPatterns

    string[] 可选

    与 documentUrlPatterns 类似，基于 img、audio 和 video 标记的 src 属性以及 a 标记的 href 属性进行过滤。

  • title

    字符串 可选

    要在项中显示的文本；除非 type 为 separator，否则此参数为必需。当上下文为 selection 时，请在字符串中使用 %s 来显示所选文本。例如，如果此参数的值为“将‘%s’翻译成 Pig Latin”，并且用户选择了“cool”一词，则所选内容的上下文菜单项为“将‘cool’翻译成 Pig Latin”。

  • 类型

    ItemType 可选

    菜单项的类型。默认为 normal。

  • 可见

    布尔值 （可选）

    该项在菜单中是否可见。

  • onclick

    void （可选）

    点击菜单项时调用的函数。这在 Service Worker 中不可用；您应该改为注册 contextMenus.onClicked 的监听器。

    onclick 函数如下所示： 

    (info: OnClickData, tab: Tab) => {...}

    • 信息

      OnClickData

      所点击商品的相关信息以及点击发生时的情境。

    • Tab

      制表符

      发生点击的标签页的详细信息。平台应用不提供此参数。

ItemType

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

菜单项的类型。

枚举

"normal"

"checkbox"

"radio"

"separator"

OnClickData

点击上下文菜单项时发送的信息。

属性

  • 已勾选

    布尔值 （可选）

    一个标志，用于指示复选框或单选按钮在被点击后的状态。

  • 可修改

    布尔值

    一个标志，用于指示元素是否可编辑（文本输入、文本区域等）。

  • frameId

    number 可选

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

    点击上下文菜单时所在元素的框架 ID（如果该元素位于框架中）。

  • frameUrl

    字符串 可选

    点击了上下文菜单的元素所在框架的网址（如果该元素位于框架中）。

  • linkUrl

    字符串 可选

    如果元素是链接，则为该链接指向的网址。

  • mediaType

    字符串 可选

    如果上下文菜单是在“图片”“视频”或“音频”类型的元素上激活的，则为其中一种类型。

  • menuItemId

    字符串 | 数字

    用户点击的菜单项的 ID。

  • pageUrl

    字符串 可选

    用户点击菜单项时所在网页的网址。如果点击发生在没有当前页面的上下文中（例如在启动器上下文菜单中），则不会设置此属性。

  • parentMenuItemId

    字符串 | 数值可选

    所点击内容的父级 ID（如有）。

  • selectionText

    字符串 可选

    上下文选择的文本（如有）。

  • srcUrl

    字符串 可选

    对于具有“src”网址的元素，此属性会存在。

  • wasChecked

    布尔值 （可选）

    一个标志，用于指示复选框或单选按钮在被点击之前的状态。

属性

ACTION_MENU_TOP_LEVEL_LIMIT

可添加到扩展程序操作上下文菜单的顶级扩展程序项数量上限。超出此上限的任何内容都会被忽略。

值

6

方法

create()

browser.contextMenus.create(
  createProperties: CreateProperties,
  callback?: function,
): number | string

创建新的上下文菜单项。如果创建期间发生错误，可能要到创建回调触发时才会检测到；详细信息将显示在 runtime.lastError 中。

参数

  • createProperties

    CreateProperties

  • callback

    函数可选

    callback 参数如下所示： 

    () => void

返回

  • number | string

    新创建的商品的 ID。

remove()

browser.contextMenus.remove(
  menuItemId: string | number,
): Promise<void>

移除上下文菜单项。

参数

  • menuItemId

    字符串 | 数字

    要移除的上下文菜单项的 ID。

返回

  • 承诺<void>

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

    在上下文菜单移除后解析。

removeAll()

browser.contextMenus.removeAll(): Promise<void>

移除此扩展程序添加的所有上下文菜单项。

返回

  • 承诺<void>

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

    在移除完成后解析。

update()

browser.contextMenus.update(
  id: string | number,
  updateProperties: object,
): Promise<void>

更新之前创建的上下文菜单项。

参数

  • id

    字符串 | 数字

    要更新的商品的 ID。

  • updateProperties

    对象

    要更新的属性。接受与 contextMenus.create 函数相同的值。

    • 已勾选

      布尔值 （可选）

    • contexts

      [ContextType, …ContextType[]] 可选

    • documentUrlPatterns

      string[] 可选

    • 已启用

      布尔值 （可选）

    • parentId

      字符串 | 数值可选

      要设为此内容的父级的内容的 ID。注意：您无法将某个项设置为其自身后代的子项。

    • targetUrlPatterns

      string[] 可选

    • title

      字符串 可选

    • 类型

      ItemType 可选

    • 可见

      布尔值 （可选）

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

      该项在菜单中是否可见。

    • onclick

      void （可选）

      onclick 函数如下所示： 

      (info: OnClickData, tab: Tab) => {...}

      • 信息

        OnClickData

        Chrome 44 及更高版本 browser.*（自 Chrome 148 起）
      • Tab

        制表符

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

        发生点击的标签页的详细信息。平台应用不提供此参数。

返回

  • 承诺<void>

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

    在上下文菜单更新后解析。

事件

onClicked

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

在点击上下文菜单项时触发。

参数