說明
使用 chrome.contextMenus API 將項目新增至 Google Chrome 的內容選單。您可以選擇內容選單增補項目適用的物件類型，例如圖片、超連結和網頁。
權限
contextMenus如要使用 API，必須在擴充功能的資訊清單中聲明 "contextMenus" 權限。此外，您應指定 16 x 16 像素的圖示，顯示在選單項目旁。例如：
{
"name": "My extension",
...
"permissions": [
"contextMenus"
],
"icons": {
"16": "icon-bitty.png",
"48": "icon-small.png",
"128": "icon-large.png"
},
...
}
概念與用途
即使是使用 file:// 或 chrome:// 網址的文件 (或文件中的影格)，也可能會顯示內容選單項目。如要控管項目可顯示的文件，請在呼叫 create() 或 update() 方法時指定 documentUrlPatterns 欄位。
您可以視需要建立任意數量的內容選單項目，但如果擴充功能有多個項目同時顯示，Google Chrome 會自動將這些項目摺疊成單一父項選單。
範例
如要試用這項 API，請從 chrome-extension-samples 存放區安裝 contextMenus API 範例。
類型
ContextType
選單可顯示的不同情境。指定「all」等同於除了「launcher」以外的所有其他情境組合。「啟動器」環境僅支援應用程式，用於在啟動器/工作列/Dock 等位置點選應用程式圖示時，將選單項目新增至顯示的內容選單。不同平台可能會限制啟動器內容選單實際支援的項目。
列舉
「all」
「page」
「frame」
「selection」
「link」
「editable」
「image」
「video」
「audio」
「launcher」
「browser_action」
「page_action」
「action」
CreateProperties
新內容選單項目的屬性。
屬性
-
已勾選
布林值 選填
核取方塊或圓形按鈕的初始狀態：
true代表已選取，false代表未選取。在特定群組中，一次只能選取一個圓形按鈕。 -
情境
[ContextType, ...ContextType[]] optional
這個選單項目會顯示的內容清單。預設值為
['page']。 -
documentUrlPatterns
字串陣列 選用
限制項目，只適用於網址符合指定模式的文件或框架。如要瞭解模式格式的詳細資料，請參閱「比對模式」。
-
已啟用
布林值 選填
這個內容選單項目是否已啟用或停用。預設值為
true。 -
id
字串 選填
指派給這個項目的專屬 ID。活動頁面必須提供這項資訊。不得與這個擴充功能的其他 ID 相同。
-
parentId
字串 | 數字 選用
父項選單項目的 ID，這會使項目成為先前新增項目的子項。
-
targetUrlPatterns
字串陣列 選用
與
documentUrlPatterns類似，篩選器會根據img、audio和video標記的src屬性，以及a標記的href屬性進行篩選。 -
title
字串 選填
要在項目中顯示的文字；除非
type為separator，否則必須提供這項資訊。如果內容為selection，請在字串中使用%s顯示所選文字。舉例來說，如果這個參數的值是「將 '%s' 翻譯成拉丁豬文」，且使用者選取「酷」這個字，選取範圍的內容選單項目就會是「將 '酷' 翻譯成拉丁豬文」。 -
類型
ItemType optional
選單項目的類型。預設值為
normal。 -
顯示
布林值 選填
項目是否顯示在選單中。
-
onclick
void optional
點選選單項目時呼叫的回呼函式。這項功能無法在 Service Worker 中使用，請改為註冊
contextMenus.onClicked的監聽器。onclick函式如下所示：(info: OnClickData, tab: Tab) => {...}
-
資訊
使用者點選的項目，以及點選時的背景資訊。
-
分頁
Tab 鍵
發生點擊的分頁詳細資料。平台應用程式沒有這個參數。
-
ItemType
選單項目的類型。
列舉
「normal」
「checkbox」
「radio」
「separator」
OnClickData
點選內容選單項目時傳送的資訊。
屬性
-
已勾選
布林值 選填
點選核取方塊或圓形按鈕項目後，表示其狀態的旗標。
-
可編輯
布林值
這個標記表示元素是否可編輯 (文字輸入、文字區域等)。
-
frameId
號碼 選填
Chrome 51 以上版本如果內容選單是在影格中點選，則為該影格的 ID。
-
frameUrl
字串 選填
如果內容選單是在影格中點選，這個元素影格的網址。
-
linkUrl
字串 選填
如果元素是連結，則為連結指向的網址。
-
mediaType
字串 選填
如果是在這類元素上啟動內容選單，則為「image」、「video」或「audio」。
-
字串 | 數字
獲得點擊的菜單項目 ID。
-
pageUrl
字串 選填
使用者點選選單項目的網頁網址。如果點擊發生在沒有目前網頁的環境中 (例如啟動器環境選單)，系統就不會設定這項屬性。
-
parentMenuItemId
字串 | 數字 選用
獲得點擊項目的父項 ID (如有)。
-
selectionText
字串 選填
內容選取範圍的文字 (如有)。
-
srcUrl
字串 選填
如果元素有「src」網址，就會顯示這個屬性。
-
wasChecked
布林值 選填
此標記用於指出核取方塊或選項按鈕在點選前的狀態。
屬性
ACTION_MENU_TOP_LEVEL_LIMIT
可新增至擴充功能動作右鍵選單的頂層擴充功能項目數量上限。系統會忽略超出這項限制的所有項目。
值
6
方法
create()
chrome.contextMenus.create(
createProperties: CreateProperties,
callback?: function,
): number | string
建立新的內容選單項目。如果在建立期間發生錯誤，可能要等到建立回呼觸發後才會偵測到，詳細資料會顯示在 runtime.lastError 中。
參數
-
createProperties
-
callback
函式 選用
callback參數如下：() => void
傳回
-
數字 | 字串
新建立項目的 ID。
remove()
chrome.contextMenus.remove(
menuItemId: string | number,
): Promise<void>
移除內容選單項目。
參數
-
字串 | 數字
要移除的內容選單項目 ID。
傳回
-
Promise<void>
Chrome 123 以上版本
removeAll()
chrome.contextMenus.removeAll(): Promise<void>
移除這個擴充功能新增的所有內容選單項目。
傳回
-
Promise<void>
Chrome 123 以上版本
update()
chrome.contextMenus.update(
id: string | number,
updateProperties: object,
): Promise<void>
更新先前建立的內容選單項目。
參數
-
id
字串 | 數字
要更新的項目 ID。
-
updateProperties
物件
要更新的屬性。接受與
contextMenus.create函式相同的值。-
已勾選
布林值 選填
-
情境
[ContextType, ...ContextType[]] optional
-
documentUrlPatterns
字串陣列 選用
-
已啟用
布林值 選填
-
parentId
字串 | 數字 選用
要設為這個項目父項的項目 ID。注意：您無法將項目設為自身後代的子項。
-
targetUrlPatterns
字串陣列 選用
-
title
字串 選填
-
類型
ItemType optional
-
顯示
布林值 選填
Chrome 62 以上版本項目是否顯示在選單中。
-
onclick
void optional
onclick函式如下所示：(info: OnClickData, tab: Tab) => {...}
-
資訊Chrome 44 以上版本
-
分頁
Tab 鍵
Chrome 44 以上版本發生點擊的分頁詳細資料。平台應用程式沒有這個參數。
-
-
傳回
-
Promise<void>
Chrome 123 以上版本
事件
onClicked
chrome.contextMenus.onClicked.addListener(
callback: function,
)
點選內容選單項目時觸發。
參數
-
callback
函式
callback參數如下：(info: OnClickData, tab?: tabs.Tab) => void
-
資訊
-
分頁
tabs.Tab 選填
-