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”之外的所有其他上下文的组合。“启动器”上下文仅受应用支持，用于向在启动器/任务栏/Dock 等位置点击应用图标时显示的菜单项添加菜单项。不同的平台可能会对启动器上下文菜单中实际支持的功能施加限制。

枚举

"selection"

"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 以显示所选文本。例如，如果此参数的值为“Translate '%s' to Pig Latin”且用户选择单词“cool”，则所选内容的上下文菜单项为“Translate 'cool' to Pig Latin”。

  • 类型

    ItemType（可选）

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

  • visible

    布尔值 选填

    相应项是否在菜单中显示。

  • onclick

    void 可选属性

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

    onclick 函数如下所示：

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

    • 资讯

      OnClickData

      所点击项的相关信息以及发生点击的上下文。

    • 标签页

      制表符

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

ItemType

Chrome 44 及更高版本

菜单项的类型。

枚举

"normal"

"radio"

OnClickData

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

属性

  • 已勾选

    布尔值 选填

    指示复选框或单选项被点击后所处的状态的标记。

  • 可编辑

    boolean

    一个标记，用于指明元素是否可修改（文本输入、文本区域等）。

  • frameId

    数字可选

    Chrome 51 及更高版本

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

  • frameUrl

    字符串（可选）

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

  • linkUrl

    字符串（可选）

    如果元素是一个链接，该元素指向的网址。

  • mediaType

    字符串（可选）

    已在这些类型的元素上激活上下文菜单，则为“图片”“视频”或“音频”。

  • menuItemId

    string|number

    获得点击的菜单项的 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

返回

  • number|string

    新创建的商品的 ID。

remove()

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

移除上下文菜单项。

参数

  • menuItemId

    string|number

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

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 123 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

removeAll()

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

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

参数

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 123 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

update()

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

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

参数

  • id

    string|number

    要更新的商品的 ID。

  • updateProperties

    对象

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

    • 已勾选

      布尔值 选填

    • 上下文

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

    • documentUrlPatterns

      string[] 可选

    • 已启用

      布尔值 选填

    • parentId

      字符串|数字，可选

      要设为该产品父级的产品的 ID。注意：您无法将某个项设置为它自己的后代的子级。

    • targetUrlPatterns

      string[] 可选

    • title

      字符串（可选）

    • 类型

      ItemType（可选）

    • visible

      布尔值 选填

      Chrome 62 及更高版本

      相应项是否在菜单中显示。

    • onclick

      void 可选属性

      onclick 函数如下所示：

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

      • 资讯

        OnClickData

        Chrome 44 及更高版本
      • 标签页

        制表符

        Chrome 44 及更高版本

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

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 123 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

活动

onClicked

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

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

参数