chrome插件中文开发文档(非官方)

右键菜单（chrome.contextMenus)

右键菜单模块允许您向Google Chrome浏览器的右键菜单添加项目

您可以选择您在右键菜单中添加的项目应用于哪些类型的对象，例如图片、超链接和页面。

您可以根据自己的需要创建任意数目的右键菜单项，但是如果您的扩展程序一次显示超过一个菜单项，Google Chrome浏览器会自动将它们折叠至一个父菜单中。

右键菜单项可以在任何文档（或文档中的框架）中出现，即使它们使用file://或chrome://协议的URL。要控制您的菜单项在哪些文档中出现，在您调用create()或update()方法时请指定documentUrlPatterns属性。

清单文件

您必须在扩展程序的清单文件中声明"contextMenus"权限来使用有关API，您还应该指定一个16×16像素的图标，显示在您的菜单项旁边。例如： 

{
  "name": "我的扩展程序",
  ...
  "permissions": [
    "contextMenus"
  ],
  "icons": {
    "16": "icon-bitty.png",
    "48": "icon-small.png",
    "128": "icon-large.png"
  },
  ...
}

例子

您可以在 示例页面找到这一API的示例。

API参考: chrome.contextMenus

类型

OnClickData

( object )
包含右键菜单项单击时发送的信息。

OnClickData属性

menuItemId ( integer or string )
单击的菜单项标识符。
parentMenuItemId ( optional integer or string )
单击的菜单项的父菜单项标识符（如果有的话）。
mediaType ( optional string )
如果右键菜单在其中某一种类型的元素上激活则值为'image'、'video'或'audio'。
linkUrl ( optional string )
如果元素是一个链接，指定它指向的URL。
srcUrl ( optional string )
如果元素的'src'属性指定了URL将会存在这一属性。
pageUrl ( string )
菜单项单击时所在页面的URL。
frameUrl ( optional string )
如果在框架中的话，单击后弹出右键菜单时框架元素的URL。
selectionText ( optional string )
当前选中的文本（如果有的话）。
editable ( boolean )
一个标志，指定当前元素是否可以编辑 (text input, textarea, 等)。
wasChecked ( optional boolean )
指示单击前复选框或单选菜单项状态的标志。
checked ( optional boolean )
指示单击后复选框或单选菜单项状态的标志。

方法

create

integer or string chrome.contextMenus.create(object createProperties)

创建一个新的右键菜单项。注意，如果创建过程中发生错误，您可能要等到回调函数调用时才能得知（详情可从chrome.runtime.lastError获得）

参数

createProperties ( object )
type ( optional enumerated string ["normal", "checkbox", "radio", "separator"] )
菜单项的类型。如果没有指定则默认为'normal'（普通）。
id ( optional string )
指派给该菜单项的唯一标志符，对于事件页面来说必须存在，不能与同一扩展程序中的其它标志符相同。
title ( optional string )
显示在菜单项中的文字，除非类型是'separator'（分隔符）该参数是必选的。 当上下文为'selection'（选定内容）时，您可以在字符串中使用%s来显示选中的文本。例如，如果参数值是“将‘%s’翻译为儿童黑话”，当用户选择一个词语“酷”时，对于选中内容的右键菜单项为“将‘酷’翻译为儿童黑话”。
checked ( optional boolean )
单选或复选菜单项的初始状态：选定为true，未选定为false。在一组单选菜单项中，一次只能有一项选定。
contexts ( optional array of enumerated string ["all", "page", "frame", "selection", "link", "editable", "image", "video", "audio"] )
列出该菜单项将会出现在哪些上下文中，包括"all"（全部）、"page"（页面）、"frame"（框架）、"selection"（选定内容）、"link"（链接）、"editable"（可编辑内容）、"image"（图片）、"video"（视频）、"audio"（音频），如果没有指定则默认为['page']（页面）
onclick ( optional function )
当菜单项单击时的回调函数。事件页面不能使用该属性，相反，它们应该为chrome.contextMenus.onClicked注册事件处理函数。
参数
info ( OnClickData )
有关单击发生时的菜单项和上下文的信息。
tab ( tabs.Tab )
单击发生的标签页的细节。
parentId ( optional integer or string )
父菜单项标识符，指定这一参数使新添加的菜单项成为原先添加菜单项的子菜单项。
documentUrlPatterns ( optional array of string )
让您将该菜单项限制在URL匹配给定表达式的文档中显示。（也适用于框架。）有关表达式的格式的细节，参见匹配表达式。
targetUrlPatterns ( optional array of string )
类似于documentUrlPatterns，但是允许您基于img/audio/video标签的src属性以及 a 标签的href属性过滤。
enabled ( optional boolean )
该右键菜单项是否启用或禁用，默认为true。

回调函数

如果您指定了callback参数, 它应该指定一个如下形式的函数：

function() {...};

update

chrome.contextMenus.update(integer or string id, object updateProperties)

更新以前创建的菜单项。

参数

id ( integer or string )
要更新的菜单项标识符。
updateProperties ( object )
要更新的属性，与create函数的createProperties参数使用的相同值
type ( optional enumerated string ["normal", "checkbox", "radio", "separator"] )
title ( optional string )
checked ( optional boolean )
contexts ( optional array of enumerated string ["all", "page", "frame", "selection", "link", "editable", "image", "video", "audio"] )
onclick ( optional function )
parentId ( optional integer or string )
注意：您不能更改菜单项，使它成为自己的子菜单。
documentUrlPatterns ( optional array of string )
targetUrlPatterns ( optional array of string )
enabled ( optional boolean )

回调函数

如果您指定了callback参数，它应该指定一个如下形式的函数：

function() {...};

remove

chrome.contextMenus.remove(integer or string menuItemId)

移除一个右键菜单项。

参数

menuItemId ( integer or string )
要移除的菜单项标识符。

Callback function

如果您指定了callback参数，它应该指定一个如下形式的函数：

function() {...};

removeAll

chrome.contextMenus.removeAll()

移除该扩展程序添加的所有右键菜单项。

事件

onClicked

chrome.contextMenus.onClicked.addListener(function(OnClickData info, tabs.Tab tab) {...});

当右键菜单项单击时产生。

监听参数

info ( OnClickData )
有关单击发生时的菜单项和上下文的信息。
tab ( optional tabs.Tab )
单击发生的标签页的细节。如果单击不在标签页中产生，将不会传递该参数。

使用chrome.contextMenus的示例程序

  • Context Menus Sample – Shows some of the features of the Context Menus API
  • Context Menus Sample (with Event Page) – Shows some of the features of the Context Menus API using an event page
  • Imageinfo – Get image info for images, including EXIF data