chrome.contextMenus

说明

使用 chrome.contextMenus API 向 Google Chrome 的上下文菜单中添加项。您可以选择从右键菜单中添加的对象类型，例如图片、超链接和页面。

权限

contextMenus

用法

上下文菜单项可以出现在任何文档（或文档中的框架）中，甚至是那些带有 file:// 的菜单项 或 chrome:// 网址。要控制您的内容可以显示在哪些文档中，请指定 documentUrlPatterns 字段。create()update()

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

清单

您必须声明“contextMenus”权限。此外，您还应指定一个 16x16 像素的图标，以用于在菜单项旁边显示。例如：

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

示例

若要试用此 API，请从 chrome-extension-samples 安装 contextMenus API 示例 存储库

类型

ContextType

Chrome 44 及更高版本

菜单可显示的不同上下文。指定“all”等同于除“launcher”以外的所有其他上下文的组合。“启动器”context 仅受应用支持，用于将菜单项添加到在启动器/任务栏/dock 等位置点击应用图标时出现的上下文菜单。不同的平台可能会限制启动器上下文菜单中实际支持的内容。

枚举

“全部”

“页面”

"框架"

“selection”

“链接”

"可修改"

“图片”

“视频”

"audio"

"launcher"

"browser_action"

"page_action"

“操作”

CreateProperties

Chrome 123 及更高版本

新上下文菜单项的属性。

属性

  • 已勾选

    布尔值（可选）

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

  • 上下文

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

    显示此菜单项的上下文列表。默认为 ['page']。

  • documentUrlPatterns

    string[] 选填

    将内容限制为仅应用于网址与某一指定格式相符的文档或框架。如需详细了解模式格式，请参阅匹配模式。

  • 已启用

    布尔值（可选）

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

  • id

    字符串（可选）

    要分配给此内容的唯一 ID。活动页面必须使用。不能与此扩展程序的另一个 ID 相同。

  • parentId

    string |编号（选填）

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

  • targetUrlPatterns

    string[] 选填

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

  • 标题

    字符串（可选）

    要在作品中显示的文本；这是必需的，除非 type 为 separator。当上下文为 selection 时，在字符串中使用 %s 以显示所选文本。例如，如果此参数的值为“Translate '%s”发送给 Pig Latin 式密语”当用户选择了“cool”一词时，可选择的上下文菜单项为“Translate cool”发送给 Pig Latin 式密语。

  • 类型

    ItemType 选填

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

  • 可见

    布尔值（可选）

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

  • onClick

    void 可选

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

    onclick 函数如下所示： 

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

    • 资讯

      OnClickData

      有关所点击项目的信息以及点击发生的具体环境。

    • Tab

      制表符

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

ItemType

Chrome 44 及更高版本

菜单项的类型。

枚举

“normal”

"checkbox"

"radio"

“separator”

OnClickData

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

属性

  • 已勾选

    布尔值（可选）

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

  • 可修改

    布尔值

    指示元素是否可修改的标志（文本输入、文本区域等）。

  • frameId

    编号（选填）

    Chrome 51 及更高版本

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

  • frameUrl

    字符串（可选）

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

  • linkUrl

    字符串（可选）

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

  • mediaType

    字符串（可选）

    “image”“video”或“audio”之一如果上下文菜单已在这类元素中激活。

  • menuItemId

    string |号码

    用户点击的菜单项的 ID。

  • pageUrl

    字符串（可选）

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

  • parentMenuItemId

    string |编号（选填）

    所点击项目的父级 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()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.contextMenus.remove(
  menuItemId: string | number,
  callback?: function,
)

移除上下文菜单项。

参数

  • menuItemId

    string |号码

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 123 及更高版本

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

removeAll()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.contextMenus.removeAll(
  callback?: function,
)

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

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 123 及更高版本

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

update()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.contextMenus.update(
  id: string | number,
  updateProperties: object,
  callback?: function,
)

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

参数

  • id

    string |号码

    要更新的商品的 ID。

  • updateProperties

    对象

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

    • 已勾选

      布尔值（可选）

    • 上下文

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

    • documentUrlPatterns

      string[] 选填

    • 已启用

      布尔值（可选）

    • parentId

      string |编号（选填）

      要设为该项的父项的 ID。注意：您无法将项设置为其子项的子项。

    • targetUrlPatterns

      string[] 选填

    • 标题

      字符串（可选）

    • 类型

      ItemType 选填

    • 可见

      布尔值（可选）

      Chrome 62 及更高版本

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

    • onClick

      void 可选

      onclick 函数如下所示： 

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

      • 资讯

        OnClickData

        Chrome 44 及更高版本
      • Tab

        制表符

        Chrome 44 及更高版本

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 123 及更高版本

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

事件

onClicked

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

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

参数