chrome.contextMenus

描述： 使用 chrome.contextMenus API 向 Google Chrome 浏览器的右键菜单添加项目。您可以选择您在右键菜单中添加的项目应用于哪些类型的对象，例如图片、超链接和页面。
可用版本： 从 Chrome 6 开始支持。
权限： "contextMenus"

用法

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

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

清单文件

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

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

例子

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

摘要

属性
ACTION_MENU_TOP_LEVEL_LIMIT
方法
create − integer or string chrome.contextMenus.create(object createProperties, function callback)
update − chrome.contextMenus.update(integer or string id, object updateProperties, function callback)
remove − chrome.contextMenus.remove(integer or string menuItemId, function callback)
removeAll − chrome.contextMenus.removeAll(function callback)
事件
onClicked

属性

6 chrome.contextMenus.ACTION_MENU_TOP_LEVEL_LIMIT

尚未完全实现，您必须通过源代码建立 Chromium 才能尝试该 API。了解更多内容

最多允许添加多少顶层扩展程序菜单项至扩展程序按钮的右键菜单中，超过该限制的菜单项将会忽略。

方法

create

integer or string chrome.contextMenus.create(object createProperties, function callback)

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

参数
object createProperties
enum of "normal", "checkbox", "radio", or "separator" （可选）
type

菜单项的类型。如果没有指定则默认为 'normal'（普通）。

string （可选）
id

从 Chrome 21 开始支持。

指派给该菜单项的唯一标志符，对于事件页面来说必须存在，不能与同一扩展程序中的其他标志符相同。

string （可选）
title

显示在菜单项中的文字，除非 type（类型）是 'separator'（分隔符），该参数是必选的。当上下文为 'selection'（选定内容）时，您可以在字符串中使用 %s 来显示选中的文本。例如，如果参数值是“将‘%s’翻译为儿童黑话”，当用户选择一个词语“酷”时，对于选中内容的右键菜单项为“将‘酷’翻译为儿童黑话”。

boolean （可选）
checked

单选或复选菜单项的初始状态：选定为 true，未选定为 false。在一组单选菜单项中，一次只能有一项选定。

array of enum of "all", "page", "frame", "selection", "link", "editable", "image", "video", "audio", "launcher", "browser_action", or "page_action" （可选）
contexts

列出该菜单项将会出现在哪些上下文中，包括 "all"（全部）、"page"（页面）、"frame"（框架）、"selection"（选定内容）、"link"（链接）、"editable"（可编辑内容）、"image"（图片）、"video"（视频）、"audio"（音频），如果没有指定则默认为 ['page']（页面），指定 ['all'] 相当于除 'launcher' 以外的所有其他上下文的组合。'launcher' 上下文仅在应用中支持，为右键菜单添加菜单项，在单击执行器/任务栏/窗格/等等中的应用图标时显示。不同的平台对于执行器中实际支持的特性可能会有一些限制。

function （可选）
onclick

当菜单项单击时的回调函数。事件页面不能使用该属性，相反，它们应该为 chrome.contextMenus.onClicked 注册事件处理函数。

参数
contextMenusInternal.OnClickData info

有关单击发生时的菜单项和上下文的信息。

tabs.Tab tab

单击发生的标签页详情。

integer or string （可选）
parentId

父菜单项标识符，指定这一参数使新添加的菜单项成为原先添加菜单项的子菜单项。

array of string （可选）
documentUrlPatterns

让您将该菜单项限制在 URL 匹配给定表达式的文档中显示。（也适用于框架。）有关表达式的格式的详情，请参见匹配表达式。

array of string （可选）
targetUrlPatterns

类似于 documentUrlPatterns，但是允许您基于 /
boolean （可选）
enabled

从 Chrome 20 开始支持。

该右键菜单项是启用还是禁用，默认为 true。

function （可选）
callback

当菜单项已经在浏览器中创建后调用。如果创建过程中出现任何错误，详情可从 runtime.lastError 获得。

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

function() {...};

update

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

更新以前创建的菜单项。

参数
integer or string id

要更新的菜单项标识符。

object updateProperties

要更新的属性，与 create 函数的 createProperties 参数使用的相同值。

enum of "normal", "checkbox", "radio", or "separator" （可选）
type
string （可选）
title
boolean （可选）
checked
array of enum of "all", "page", "frame", "selection", "link", "editable", "image", "video", "audio", "launcher", "browser_action", or "page_action" （可选）
contexts
function （可选）
onclick
integer or string （可选）
parentId

注意：您不能更改菜单项，使它成为自己的子菜单。

array of string （可选）
documentUrlPatterns
array of string （可选）
targetUrlPatterns
boolean （可选）
enabled

从 Chrome 20 开始支持。

function （可选）
callback

右键菜单项更新后调用。

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

function() {...};

remove

chrome.contextMenus.remove(integer or string menuItemId, function callback)

移除右键菜单项。

参数
integer or string menuItemId

要移除的菜单项标识符。

function （可选）
callback

右键菜单项移除后调用。

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

function() {...};

removeAll

chrome.contextMenus.removeAll(function callback)

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

参数
function （可选）
callback

移除完成后调用。

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

function() {...};

事件

onClicked

从 Chrome 21 开始支持。

addListener

chrome.contextMenus.onClicked.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数：

function() {...};

示例扩展程序