# Context Menus
## 内容
1. [清单](contextMenus.html#manifest)
2. [范例](contextMenus.html#examples)
3. [API 参考: Chrome.contextMenus](contextMenus.html#apiReference)
1. [方法](contextMenus.html#global-methods)
1. [create](contextMenus.html#method-create)
2. [remove](contextMenus.html#method-remove)
3. [removeAll](contextMenus.html#method-removeAll)
4. [update](contextMenus.html#method-update)
2. [类型](contextMenus.html#types)
1. [OnClickData](contextMenus.html#type-OnClickData)
Context菜单用于在Chrome的右键菜单中增加自己的菜单项。
您可以选择针对不同类型的对象（如图片，链接，页面）增加右键菜单项。
您可以根据需要添加多个右键菜单项。一个扩展里添加的多个右键菜单项会被Chrome自动组合放到对应扩展名称的二级菜单里。
右键菜单可以出现在任意文档（或文档中的框架）中，甚至是本地文件（如file://或者Chrome://）中。若想控制右键菜单在不同文档中的显示，可以在调用create()和update()时指定documentUrlPatterns。
**版本说明：** 低于Chrome 14的版本,右键菜单只能用于http:// 或者 https:// 类型的文档。
## 清单
要使用contentMenus API，您必须在清单中声明“contentMenus”权限。同时，您应该指定一个16x16的图标用作右键菜单的标识。例如：
<a name="h2-2">
```
{
"name": "My extension",
...
"permissions": [
**"contextMenus"**
],
"icons": {
**"16": "icon-bitty.png",**
"48": "icon-small.png",
"128": "icon-large.png"
},
...
}
```
</a>
## 范例
您可以在[代码例子页面](samples.html#contextMenus)找到使用contentMenus API的简单范例。
## API 参考: Chrome.contextMenus
### 方法
#### create
integer Chrome.contextMenus.create(object `createProperties`, function `callback`)
创建一个新的右键菜单项。注意：如果在创建的过程中出现错误，会在回调函数触发后才能捕获到，错误详细信息保存在Chrome.extension.lastError中。
#### 参数
`createProperties`_( object )_
Undocumented.
`type`_( optional enumerated string ["normal", "checkbox", "radio", "separator"] )_
右键菜单项的类型。默认为“normal”。
`title`_( optional string )_
右键菜单项的显示文字；除非为“separator”_类型_，否则此参数是_必须_的。如果类型为“selection”，您可以在字符串中使用`%s`显示选定的文本。例如，如果参数的值为 "Translate '%s' to Pig Latin"，而用户还选中了文本“cool”，那么显示在菜单中的将会是 "Translate 'cool' to Pig Latin"。
`checked`_( optional boolean )_
Checkbox或者radio的初始状态：true代表选中，false代表未选中。在给定的radio中只能有一个处于选中状态。
`contexts`_( optional array of string ["all", "page", "frame", "selection", "link", "editable", "image", "video", "audio"] )_
右键菜单项将会在这个列表指定的上下文类型中显示。默认为“page”。
`onclick`_( optional function )_
当菜单项被点击时触发的函数。
##### 参数
`info`_( [OnClickData](contextMenus.html#type-OnClickData) )_
右键菜单项被点击时相关的上下文信息。
`tab`_( [Tab](tabs.html#type-Tab) )_
右键菜单项被点击时，当前标签的详细信息。
`parentId`_( optional integer )_
右键菜单项的父菜单项ID。指定父菜单项将会使此菜单项成为父菜单项的子菜单。
`documentUrlPatterns`_( optional array of string )_
这使得右键菜单只在匹配此模式的url页面上生效（这个对框架也适用）。详细的匹配格式见：[模式匹配页面](match_patterns.html)。
`targetUrlPatterns`_( optional array of string )_
类似于documentUrlPatterns，但是您可以针对img/audio/video标签的src属性和anchor标签的href做过滤。
`enabled`_( optional boolean )_
启用或者禁用此菜单项，启用为true，禁用为false。默认为true。
`callback`_( optional function )_
在创建完菜单项后触发。如果创建过程中有错误产生，其详细信息在Chrome.extension.lastError中。
#### 返回
_( integer )_
新创建右键菜单项的ID。
#### 回调
如果需要指定_回调函数_，则回调函数格式如下：
```
function() {...};
```
#### remove
Chrome.contextMenus.remove(integer `menuItemId`, function `callback`)
删除一个右键菜单。
#### 参数
`menuItemId`_( integer )_
待删除的右键菜单项的ID
`callback`_( optional function )_
当右键菜单项被删除后触发。
#### 回调
如果需要指定_回调函数_，则回调函数格式如下：
```
function() {...};
```
#### removeAll
Chrome.contextMenus.removeAll(function `callback`)
删除此扩展添加的所有右键菜单项。
#### 参数
`callback`_( optional function )_
删除完成后触发。
#### 回调
如果需要指定_回调函数_，则回调函数格式如下：
```
function() {...};
```
#### update
Chrome.contextMenus.update(integer `id`, object `updateProperties`, function `callback`)
更新已创建的右键菜单项。
#### 参数
`id`_( integer )_
待更新的右键菜单项的ID.
`updateProperties`_( object )_
待更新的属性。与创建右键菜单项时的属性参数一样。
`type`_( optional enumerated string ["normal", "checkbox", "radio", "separator"] )_
Undocumented.
`title`_( optional string )_
Undocumented.
`checked`_( optional boolean )_
Undocumented.
`contexts`_( optional array of string ["all", "page", "frame", "selection", "link", "editable", "image", "video", "audio"] )_
Undocumented.
`onclick`_( optional function )_
Undocumented.
`parentId`_( optional integer )_
注意：不能将右键菜单项设置成自己子菜单的子菜单。
`documentUrlPatterns`_( optional array of string )_
Undocumented.
`targetUrlPatterns`_( optional array of string )_
Undocumented.
`enabled`_( optional boolean )_
Undocumented.
`callback`_( optional function )_
右键菜单项更新完成后触发。
#### 回调
如果需要指定_回调函数_，则回调函数格式如下：
```
function() {...};
```
### 类型
#### OnClickData
_( object )_
当右键菜单项被点击时的信息。
`menuItemId`_( integer )_
被点击的右键菜单项的ID。
`parentMenuItemId`_( optional integer )_
被点击的右键菜单项的父菜单（如果存在）ID。
`mediaType`_( optional string )_
点击激活此右键菜单项时，被点击的元素的类型，如:'image', 'video'或者 'audio'。
`linkUrl`_( optional string )_
链接的url（如果被点击的元素是链接）。
`srcUrl`_( optional string )_
如果被点击元素有 'src' 属性。
`pageUrl`_( string )_
点击所在页面的URL。
`frameUrl`_( optional string )_
框架元素的URL（如果点击的元素是一个框架）。
`selectionText`_( optional string )_
如果点击时选择了文本，则为选中的文本内容。
`editable`_( string )_
被点击的元素是否可编辑，比如文本输入框就是可编辑的。
- 基础文档
- 综述
- 调试
- 格式：Manifest文件
- 模式匹配
- 改变浏览器外观
- Browser Actions
- Context Menus
- 桌面通知
- Omnibox
- Override替代页
- Page Actions
- 主题
- 与浏览器交互
- 书签
- Cookies
- chrome.devtools.* APIs
- Events
- chrome.history
- Management
- 标签
- 视窗
- 实现扩展
- 无障碍性(a11y)
- 背景页
- Content Scripts
- 跨域 XMLHttpRequest 请求
- 国际化 (i18n)
- 消息传递
- Optional Permissions
- NPAPI 插件
- 完成并发布应用
- 自动升级
- 托管
- 打包
- 规范和协议
- 应用设计规范
- 开发人员协议
- 免责声明