chrome.contextMenus

说明

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

权限

contextMenus

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

{
  "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”之外的所有其他情境。只有应用支持“启动器”上下文，用于向在启动器/任务栏/底板/等中点击应用图标时显示的上下文菜单中添加菜单项。不同平台可能会对启动器上下文菜单中实际支持的内容施加限制。

枚举

“all”

"page"

"frame"

"selection"

"link"

"editable"

"image"

"video"

"audio"

"launcher"

"browser_action"

"page_action"

"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’翻译为猪拉丁语”，并且用户选择了“cool”一词，则相应选择项的上下文菜单项为“将‘cool’翻译为猪拉丁语”。

  • 类型

    ItemType（商品类型）- 可选

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

  • 可见

    布尔值（可选）

    菜单中是否显示该项。

  • onclick

    void 可选

    在点击菜单项时调用的函数。此方法无法在 Service Worker 中使用；您应为 contextMenus.onClicked 注册监听器。

    onclick 函数如下所示： 

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

    • 资讯

      OnClickData

      有关点击的项目和点击发生情境的信息。

    • Tab

      制表符

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

ItemType

Chrome 44 及更高版本

菜单项的类型。

枚举

“normal”

"checkbox"

"radio"

"separator"

OnClickData

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

属性

  • 已勾选

    布尔值（可选）

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

  • 可修改

    布尔值

    一个标志，指示元素是否可编辑（文本输入框、textarea 等）。

  • frameId

    number 可选

    Chrome 51 及更高版本

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

  • frameUrl

    字符串（选填）

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

  • linkUrl

    字符串（选填）

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

  • mediaType

    字符串（选填）

    如果上下文菜单是在某种类型的元素上启用的，则为“图片”“视频”或“音频”之一。

  • menuItemId

    字符串 | 数字

    用户点击的菜单项的 ID。

  • pageUrl

    字符串（选填）

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

  • parentMenuItemId

    字符串 | 数字（可选）

    点击的项的父 ID（如果有）。

  • selectionText

    字符串（选填）

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

  • srcUrl

    字符串（选填）

    适用于具有“src”网址的元素。

  • wasChecked

    布尔值（可选）

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

属性

ACTION_MENU_TOP_LEVEL_LIMIT

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

值

6

方法

create()

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

创建新的上下文菜单项。如果创建期间发生错误，系统可能不会在创建回调触发之前检测到该错误；详情将在 runtime.lastError 中。

参数

  • createProperties

    CreateProperties

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 数字 | 字符串

    新创建的项的 ID。

remove()

prometido 
chrome.contextMenus.remove(
  menuItemId: string | number,
  callback?: function,
)

移除上下文菜单项。

参数

  • menuItemId

    字符串 | 数字

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 123 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

removeAll()

prometido 
chrome.contextMenus.removeAll(
  callback?: function,
)

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

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 123 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

update()

prometido 
chrome.contextMenus.update(
  id: string | number,
  updateProperties: object,
  callback?: function,
)

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

参数

  • id

    字符串 | 数字

    要更新的项的 ID。

  • updateProperties

    对象

    要更新的媒体资源。接受与 contextMenus.create 函数相同的值。

    • 已勾选

      布尔值（可选）

    • 上下文

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

    • documentUrlPatterns

      string[] 可选

    • 已启用

      布尔值（可选）

    • parentId

      字符串 | 数字（可选）

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

    • targetUrlPatterns

      string[] 可选

    • title

      字符串（选填）

    • 类型

      ItemType（商品类型）- 可选

    • 可见

      布尔值（可选）

      Chrome 62 及更高版本

      菜单中是否显示该项。

    • onclick

      void 可选

      onclick 函数如下所示： 

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

      • 资讯

        OnClickData

        Chrome 44 及更高版本
      • Tab

        制表符

        Chrome 44 及更高版本

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 123 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

事件

onClicked

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

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

参数