chrome.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，请从 chrome-extension-samples 代码库中安装 contextMenus API 示例。

类型

ContextType

Chrome 44 及更高版本

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

枚举

“全部”

“page”

“frame”

“选择”

“链接”

“可修改”

“图片”

“视频”

“音频”

“启动器”

"browser_action"

"page_action"

“操作”

CreateProperties

Chrome 123 及更高版本

新上下文菜单项的属性。

属性

  • 已勾选

    布尔值（可选）

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

  • 上下文

    [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 optional

    点击菜单项时调用的回调函数。此属性在 Service Worker 内不可用；您应改为为 contextMenus.onClicked 注册监听器。

    onclick 函数如下所示： 

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

    • 资讯

      OnClickData

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

    • Tab

      制表符

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

ItemType

Chrome 44 及更高版本

菜单项的类型。

枚举

“normal”

“checkbox”

“radio”

"separator"

OnClickData

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

属性

  • 已勾选

    布尔值（可选）

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

  • 可修改

    布尔值

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

  • frameId

    number 可选

    Chrome 51 及更高版本

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

  • frameUrl

    字符串（选填）

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

  • linkUrl

    字符串（选填）

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

  • mediaType

    字符串（选填）

    如果上下文菜单是在以下类型的元素上激活的，则为“image”“video”或“audio”之一。

  • menuItemId

    字符串 | 数字

    获得点击的菜单项的 ID。

  • pageUrl

    字符串（选填）

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

  • parentMenuItemId

    字符串 | 数值可选

    所点击商品的父 ID（如有）。

  • selectionText

    字符串（选填）

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

  • srcUrl

    字符串（选填）

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

  • wasChecked

    布尔值（可选）

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

属性

ACTION_MENU_TOP_LEVEL_LIMIT

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

值

6

方法

create()

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

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

参数

  • createProperties

    CreateProperties

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • number | string

    新创建的商品的 ID。

remove()

Promise 
chrome.contextMenus.remove(
  menuItemId: string | number,
  callback?: function,
): Promise<void>

移除上下文菜单项。

参数

  • menuItemId

    字符串 | 数字

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

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 123 及更高版本

removeAll()

Promise 
chrome.contextMenus.removeAll(
  callback?: function,
): Promise<void>

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

参数

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 123 及更高版本

update()

Promise 
chrome.contextMenus.update(
  id: string | number,
  updateProperties: object,
  callback?: function,
): Promise<void>

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

参数

  • id

    字符串 | 数字

    要更新的商品的 ID。

  • updateProperties

    对象

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

    • 已勾选

      布尔值（可选）

    • 上下文

      [ContextType, ...ContextType[]] 可选

    • documentUrlPatterns

      string[] 可选

    • 已启用

      布尔值（可选）

    • parentId

      字符串 | 数值可选

      要设为相应商品父级的商品的 ID。注意：您无法将某个项目设置为其自身后代的子项。

    • targetUrlPatterns

      string[] 可选

    • title

      字符串（选填）

    • 类型

      ItemType 可选

    • 可见

      布尔值（可选）

      Chrome 62 及更高版本

      相应项是否在菜单中可见。

    • onclick

      void optional

      onclick 函数如下所示： 

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

      • 资讯

        OnClickData

        Chrome 44 及更高版本
      • Tab

        制表符

        Chrome 44 及更高版本

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

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 123 及更高版本

事件

onClicked

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

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

参数