说明
请使用 chrome.contextMenus
API 向 Google Chrome 的上下文菜单添加项。您可以选择要在上下文菜单中添加的对象的类型,例如图片、超链接和页面。
权限
contextMenus
用量
上下文菜单项可以出现在任何文档(或文档框架)中,即使是带有 file:// 或 chrome:// 网址的文档。如需控制这些项可以显示在哪些文档中,请在调用 create()
或 update()
方法时指定 documentUrlPatterns 字段。
您可以根据需要创建任意数量的上下文菜单项,但如果系统一次性显示了扩展程序中的多项菜单项,Google Chrome 会自动将它们收起到一个父菜单中。
清单
您必须在扩展程序的清单中声明“contextMenus”权限,才能使用该 API。此外,您应指定一个 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
菜单可出现在哪些不同上下文中。指定“all”相当于除“launcher”之外的所有其他上下文的组合。“启动器”上下文仅受应用支持,用于向在启动器/任务栏/Dock 等位置点击应用图标时显示的菜单项添加菜单项。不同的平台可能会对启动器上下文菜单中实际支持的功能施加限制。
枚举
"selection"
"audio"
"launcher"
"browser_action"
"page_action"
"action"
CreateProperties
新上下文菜单项的属性。
属性
-
已勾选
布尔值 选填
复选框或单选按钮的初始状态:
true
表示已选中,false
表示未选中。在给定组中,一次只能选择一个单选按钮。 -
上下文
[ContextType, ...ContextType[]] 可选
将出现此菜单项的上下文列表。默认为
['page']
。 -
documentUrlPatterns
string[] 可选
将项目限制为仅适用于网址与给定格式之一匹配的文档或框架。要详细了解模式格式,请参阅匹配模式。
-
已启用
布尔值 选填
此上下文菜单项处于启用还是停用状态。默认为
true
。 -
id
字符串(可选)
要分配给此项的唯一 ID。必须为活动页面提供。不能与此附加信息的其他 ID 相同。
-
parentId
string | 数字(可选)
父菜单项的 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) => {...}
-
资讯
所点击项的相关信息以及发生点击的上下文。
-
标签页
发生点击的标签页的详细信息。平台应用没有此参数。
-
ItemType
菜单项的类型。
枚举
"normal"
"radio"
OnClickData
点击上下文菜单项时发送的信息。
属性
-
已勾选
布尔值 选填
指示复选框或单选项被点击后所处的状态的标记。
-
可编辑
boolean
一个标记,用于指明元素是否可修改(文本输入、文本区域等)。
-
frameId
数字可选
Chrome 51 及更高版本您点击上下文菜单时所在元素的 ID(如果该元素位于框架中)。
-
frameUrl
字符串(可选)
点击上下文菜单的元素所在框架的网址(如果该元素位于框架中)。
-
linkUrl
字符串(可选)
如果元素是一个链接,该元素指向的网址。
-
mediaType
字符串(可选)
已在这些类型的元素上激活上下文菜单,则为“图片”“视频”或“音频”。
-
字符串 | 数字
获得点击的菜单项的 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
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
数字 | 字符串
新创建的商品的 ID。
remove()
chrome.contextMenus.remove(
menuItemId: string | number,
callback?: function,
)
移除上下文菜单项。
参数
-
字符串 | 数字
要移除的上下文菜单项的 ID。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 123 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
removeAll()
chrome.contextMenus.removeAll(
callback?: function,
)
移除此扩展程序添加的所有上下文菜单项。
参数
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 123 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
update()
chrome.contextMenus.update(
id: string | number,
updateProperties: object,
callback?: function,
)
更新之前创建的上下文菜单项。
参数
-
id
字符串 | 数字
要更新的商品的 ID。
-
updateProperties
对象
要更新的属性。接受与
contextMenus.create
函数相同的值。-
已勾选
布尔值 选填
-
上下文
[ContextType, ...ContextType[]] 可选
-
documentUrlPatterns
string[] 可选
-
已启用
布尔值 选填
-
parentId
string | 数字(可选)
要设为该产品父级的产品的 ID。注意:您无法将某个项设置为它自己的后代的子级。
-
targetUrlPatterns
string[] 可选
-
title
字符串(可选)
-
类型
ItemType(可选)
-
visible
布尔值 选填
Chrome 62 及更高版本相应项是否在菜单中显示。
-
onclick
void 可选属性
onclick
函数如下所示:(info: OnClickData, tab: Tab) => {...}
-
资讯Chrome 44 及更高版本
-
标签页Chrome 44 及更高版本
发生点击的标签页的详细信息。平台应用没有此参数。
-
-
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 123 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
活动
onClicked
chrome.contextMenus.onClicked.addListener(
callback: function,
)
点击上下文菜单项时触发。
参数
-
callback
功能
callback
参数如下所示:(info: OnClickData, tab?: tabs.Tab) => void
-
资讯
-
标签页
tabs.Tab 可选
-