chrome.contextMenus
| 描述： |
使用 chrome.contextMenus API 向 Google Chrome 浏览器的右键菜单添加项目。您可以选择您在右键菜单中添加的项目应用于哪些类型的对象，例如图片、超链接和页面。
|
| 可用版本： |
从 Chrome 6 开始稳定支持。
|
| 权限： |
"contextMenus"
|
用法
右键菜单项可以在任何文档（或文档中的框架）中出现，即使它们使用
file:// 或 chrome:// 协议的 URL。要控制您的菜单项在哪些文档中出现，在您调用
create() 或 update() 方法时请指定 documentUrlPatterns 属性。
您可以根据自己的需要创建任意数目的右键菜单项，但是如果您的扩展程序一次显示超过一个菜单项，Google Chrome 浏览器会自动将它们折叠至一个父菜单中。
清单文件
您必须在应用的清单文件中声明 "contextMenus" 权限才能使用有关
API。例如：
{
"name": "我的扩展程序",
...
"permissions": [
"contextMenus"
],
...
}
例子
您可以在示例页面找到这一 API 的示例。
类型
OnClickData
包含右键菜单项单击时发送的信息。
-
-
如果右键菜单在其中某一种类型的元素上激活则值为'image'、'video' 或 'audio'。
-
linkUrl
(
optional
string
)
-
如果元素是一个链接，指定它指向的 URL。
-
srcUrl
(
optional
string
)
-
如果元素的 src 属性指定了 URL 将会存在这一属性。
-
pageUrl
(
optional
string
)
-
菜单项单击时所在页面的 URL。如果单击时所在上下文没有当前页面，例如在应用执行器的右键菜单中，则不会设置该属性。
-
frameUrl
(
optional
string
)
-
如果在框架中的话，则为单击后弹出右键菜单时框架元素的 URL。
-
selectionText
(
optional
string
)
-
当前选中的文本（如果有的话）。
-
editable
(
boolean
)
-
一个标志，指定当前元素是否可以编辑（<input type="text">、<textarea> 等）。
-
wasChecked
(
optional
boolean
)
-
表示单击前复选框或单选菜单项状态的标志。
-
checked
(
optional
boolean
)
-
表示单击后复选框或单选菜单项状态的标志。
方法
create
integer or string chrome.contextMenus.create(object createProperties, function callback)
创建一个新的右键菜单项。注意，如果创建过程中发生错误，您可能要等到回调函数调用时才能得知（详情可从 runtime.lastError 获得）
参数
-
createProperties
(
object
)
-
-
属性
-
type
(
optional
enum of "normal", "checkbox", "radio", or "separator"
)
-
菜单项的类型。如果没有指定则默认为 'normal'（普通）。
-
id
(
optional
string
)
-
指派给该菜单项的唯一标志符，对于事件页面来说必须存在，不能与同一扩展程序中的其他标志符相同。
-
title
(
optional
string
)
-
显示在菜单项中的文字，除非 type（类型）是 'separator'（分隔符），该参数是必选的。当上下文为 'selection'（选定内容）时，您可以在字符串中使用
%s 来显示选中的文本。例如，如果参数值是“将‘%s’翻译为儿童黑话”，当用户选择一个词语“酷”时，对于选中内容的右键菜单项为“将‘酷’翻译为儿童黑话”。
-
checked
(
optional
boolean
)
-
单选或复选菜单项的初始状态：选定为 true，未选定为 false。在一组单选菜单项中，一次只能有一项选定。
-
contexts
(
optional
array of enum of "all", "page", "frame", "selection", "link", "editable", "image", "video", "audio", or "launcher"
)
-
列出该菜单项将会出现在哪些上下文中，包括 "all"（全部）、"page"（页面）、"frame"（框架）、"selection"（选定内容）、"link"（链接）、"editable"（可编辑内容）、"image"（图片）、"video"（视频）、"audio"（音频），如果没有指定则默认为 ['page']（页面），指定 ['all'] 相当于除 'launcher' 以外的所有其他上下文的组合。'launcher' 上下文仅在应用中支持，为右键菜单添加菜单项，在单击执行器/任务栏/窗格/等等中的应用图标时显示。不同的平台对于执行器中实际支持的特性可能会有一些限制。
-
onclick
(
optional
function
)
-
当菜单项单击时的回调函数。事件页面不能使用该属性，相反，它们应该为 chrome.contextMenus.onClicked 注册事件处理函数。
-
参数
-
parentId
(
optional
integer or
string
)
-
父菜单项标识符，指定这一参数使新添加的菜单项成为原先添加菜单项的子菜单项。
-
documentUrlPatterns
(
optional
array of string
)
-
让您将该菜单项限制在 URL 匹配给定表达式的文档中显示。（也适用于框架。）有关表达式的格式的详情，请参见匹配表达式。
-
targetUrlPatterns
(
optional
array of string
)
-
类似于 documentUrlPatterns，但是允许您基于
![]()
/
-
enabled
(
optional
boolean
)
-
该右键菜单项是启用还是禁用，默认为 true。
-
callback
(
optional
function
)
-
当菜单项已经在浏览器中创建后调用。如果创建过程中出现任何错误，详情可从 runtime.lastError 获得。
如果您指定了 callback 参数，它应该指定一个如下形式的函数：
function() {...};
update
chrome.contextMenus.update(integer or string id, object updateProperties, function callback)
更新以前创建的菜单项。
参数
-
id
(
integer or
string
)
-
要更新的菜单项标识符。
-
updateProperties
(
object
)
-
要更新的属性，与 create 函数的 createProperties 参数使用的相同值。
-
属性
-
type
(
optional
enum of "normal", "checkbox", "radio", or "separator"
)
-
-
title
(
optional
string
)
-
-
checked
(
optional
boolean
)
-
-
contexts
(
optional
array of enum of "all", "page", "frame", "selection", "link", "editable", "image", "video", "audio", or "launcher"
)
-
-
onclick
(
optional
function
)
-
-
parentId
(
optional
integer or
string
)
-
注意：您不能更改菜单项，使它成为自己的子菜单。
-
documentUrlPatterns
(
optional
array of string
)
-
-
targetUrlPatterns
(
optional
array of string
)
-
-
enabled
(
optional
boolean
)
-
-
callback
(
optional
function
)
-
右键菜单项更新后调用。
如果您指定了 callback 参数，它应该指定一个如下形式的函数：
function() {...};
remove
chrome.contextMenus.remove(integer or string menuItemId, function callback)
移除右键菜单项。
参数
-
callback
(
optional
function
)
-
右键菜单项移除后调用。
如果您指定了 callback 参数，它应该指定一个如下形式的函数：
function() {...};
removeAll
chrome.contextMenus.removeAll(function callback)
移除该扩展程序添加的所有右键菜单项。
参数
-
callback
(
optional
function
)
-
移除完成后调用。
如果您指定了 callback 参数，它应该指定一个如下形式的函数：
function() {...};
事件
onClicked
当右键菜单项单击时产生。
addListener
chrome.contextMenus.onClicked.addListener(function callback)
参数
callback 参数应该指定一个如下形式的函数：
function(OnClickData info, tabs.Tab tab) {...};
-
tab
(
optional
tabs.Tab
)
-
单击发生的标签页的细节。如果单击不在标签页中产生，将不会传递该参数。
chrome