chrome.contextMenus
| Description: |
Use the chrome.contextMenus API to add items to Google Chrome's context menu. You can choose what types of objects your context menu additions apply to, such as images, hyperlinks, and pages.
|
| Availability: |
Since Chrome 35.
|
| Permissions: |
"contextMenus"
|
Usage
Context menu items can appear in any document (or frame within a document), even those with file:// or chrome:// URLs. To control which documents your items can appear in, specify the documentUrlPatterns field when you call the create() or update() method.
You can create as many context menu items as you need, but if more than one from your extension is visible at once, Google Chrome automatically collapses them into a single parent menu.
Manifest
You must declare the "contextMenus" permission in your extension's manifest to use the API. Also, you should specify a 16x16-pixel icon for display next to your menu item. For example:
{
"name": "My extension",
...
"permissions": [
"contextMenus"
],
"icons": {
"16": "icon-bitty.png",
"48": "icon-small.png",
"128": "icon-large.png"
},
...
}
Examples
You can find samples of this API on the sample page.
Summary
| Types | |
|---|---|
| ContextType | |
| ItemType | |
| Properties | |
| ACTION_MENU_TOP_LEVEL_LIMIT | |
| Methods | |
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)
| |
| Events | |
| onClicked | |
Types
ContextType
| Enum |
|---|
"all",
"page",
"frame",
"selection",
"link",
"editable",
"image",
"video",
"audio",
"launcher",
"browser_action",
"page_action",
or "action"
|
ItemType
| Enum |
|---|
"normal",
"checkbox",
"radio",
or "separator"
|
Properties
6 |
chrome.contextMenus.ACTION_MENU_TOP_LEVEL_LIMIT |
Since Chrome 38. The maximum number of top level extension items that can be added to an extension action context menu. Any items beyond this limit will be ignored. |
Methods
create
integer or
string
chrome.contextMenus.create(object createProperties, function callback)
Creates a new context menu item. If an error occurs during creation, it may not be detected until the creation callback fires; details will be in runtime.lastError.
| Parameters | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| object | createProperties |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| function | (optional) callback |
Called when the item has been created in the browser. If an error occurs during creation, details will be available in runtime.lastError. If you specify the callback parameter, it should be a function that looks like this: function() {...};
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
update
chrome.contextMenus.update(integer or string id, object updateProperties, function callback)
Updates a previously created context menu item.
| Parameters | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| integer or string | id |
The ID of the item to update. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| object | updateProperties |
The properties to update. Accepts the same values as the contextMenus.create function.
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| function | (optional) callback |
Called when the context menu has been updated. If you specify the callback parameter, it should be a function that looks like this: function() {...};
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
remove
chrome.contextMenus.remove(integer or string menuItemId, function callback)
Removes a context menu item.
| Parameters | ||
|---|---|---|
| integer or string | menuItemId |
The ID of the context menu item to remove. |
| function | (optional) callback |
Called when the context menu has been removed. If you specify the callback parameter, it should be a function that looks like this: function() {...};
|
removeAll
chrome.contextMenus.removeAll(function callback)
Removes all context menu items added by this extension.
| Parameters | ||
|---|---|---|
| function | (optional) callback |
Called when removal is complete. If you specify the callback parameter, it should be a function that looks like this: function() {...};
|
Events
onClicked
Fired when a context menu item is clicked.
addListener
chrome.contextMenus.onClicked.addListener(function callback)
| Parameters | ||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| function | callback |
The callback parameter should be a function that looks like this: function(object info, tabs.Tab tab) {...};
|
||||||||||||||||||||||||||||||||||||||||||