Context Menus · Chrome 擴展開發文檔

# 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 )_ 被點擊的元素是否可編輯，比如文本輸入框就是可編輯的。