說明
使用 chrome.contextMenus
API 將項目新增至 Google Chrome 的內容選單。您可以選擇內容選單要新增的物件類型,例如圖片、超連結和網頁。
權限
contextMenus
您必須在擴充功能的資訊清單中宣告 "contextMenus"
權限,才能使用 API。此外,您應該為選單項目旁指定 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
選單可顯示的不同情境。除了「launcher」以外,指定「all」等同於所有其他結構定義的組合。「啟動器」內容僅適用於應用程式,可用來將選單項目加入至點選啟動器/taskbar/dock 等應用程式圖示時顯示的內容選單。不同平台可能會對啟動器內容選單實際支援的功能有所限制。
列舉
"selection"
"browser_action"
"page_action"
CreateProperties
新內容選單項目的屬性。
屬性
-
已勾選
布林值 (選用)
核取方塊或圓形按鈕的初始狀態:已選取
true
為已選取,false
為未選取。在每個群組中,一次只能選取一個圓形按鈕。 -
情境
[ContextType, ...ContextType[]] 選用
顯示這個選單項目的背景資訊清單。預設值為
['page']
。 -
documentUrlPatterns
string[] 選填
限制項目僅適用於網址符合任一指定模式的文件或頁框。如要進一步瞭解模式格式,請參閱比對模式。
-
已啟用
布林值 (選用)
用於啟用或停用內容選單項目。預設值為
true
。 -
id
字串 選用
指派給這個項目的專屬 ID。這是活動網頁的必要項目。不得與這則額外資訊的其他 ID 相同。
-
parentId
string | number 選填
父項選單項目的 ID;這會將這個項目設為先前新增項目的子項。
-
targetUrlPatterns
string[] 選填
與
documentUrlPatterns
類似,根據img
、audio
和video
標記的src
屬性以及a
標記的href
屬性篩選。 -
title
字串 選用
要在項目中顯示的文字;這是必要項目,除非
type
是separator
。結構定義為selection
時,請在字串中使用%s
來顯示所選文字。舉例來說,如果此參數值是「 Translate '%s' to Pig Latin」,且使用者選取「cool」一詞,則選取內容選單項目為「將 'cool' to Pig Latin」。 -
類型
ItemType 選用
選單項目的類型。預設值為
normal
。 -
顯示
布林值 (選用)
是否在選單中顯示項目。
-
onclick
void optional
使用者點選選單項目時呼叫的函式。這無法在 Service Worker 內使用,請改為註冊
contextMenus.onClicked
的事件監聽器。onclick
函式如下所示:(info: OnClickData, tab: Tab) => {...}
-
資訊
點選的項目和點擊所在環境的相關資訊。
-
分頁
Tab 鍵
發生點擊的分頁詳細資料。平台應用程式沒有這個參數。
-
ItemType
選單項目的類型。
列舉
OnClickData
當使用者點選內容選單項目時傳送的資訊。
屬性
-
已勾選
布林值 (選用)
指出核取方塊或圓形按鈕在點選後狀態的標記。
-
可編輯
boolean
此標記表示元素是否可以編輯 (文字輸入、文字區域等)。
-
frameId
數字 選填
Chrome 51 以上版本獲點擊內容選單的元素頁框 ID (如果元素是在頁框中)。
-
frameUrl
字串 選用
使用者點擊內容選單時所在頁框的網址 (如果元素是在頁框中)。
-
linkUrl
字串 選用
如果元素為連結,則會指向連結的網址。
-
mediaType
字串 選用
如果其中一種元素已啟用內容選單,請選取「圖片」、「影片」或「音訊」。
-
string | number
點選的選單項目的 ID。
-
pageUrl
字串 選用
點選選單項目的網頁網址。如果點擊是在沒有目前網頁的內容 (例如啟動器內容選單) 中發生,系統就不會設定這個屬性,
-
parentMenuItemId
string | number 選填
點擊項目的父項 ID (如有)。
-
selectionText
字串 選用
內容選取範圍的文字 (如有)。
-
srcUrl
字串 選用
將會顯示在含有「src」網址的元素上。
-
wasChecked
布林值 (選用)
此標記表示核取方塊或圓形按鈕在點選前的狀態。
屬性
ACTION_MENU_TOP_LEVEL_LIMIT
可加入擴充功能動作內容選單的頂層擴充功能項目數量上限。系統會忽略超出這項限制的所有項目。
值
6
方法
create()
chrome.contextMenus.create(
createProperties: CreateProperties,
callback?: function,
)
建立新的內容選單項目。如果建立時發生錯誤,可能要等到建立回呼啟動後才會偵測到錯誤,詳情請參閱 runtime.lastError
。
參數
-
createProperties
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
數字 | 字串
新建立項目的 ID。
remove()
chrome.contextMenus.remove(
menuItemId: string | number,
callback?: function,
)
移除內容選單項目。
參數
-
string | number
要移除的內容選單項目 ID。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 123 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
removeAll()
chrome.contextMenus.removeAll(
callback?: function,
)
移除這個擴充功能新增的所有內容選單項目。
參數
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 123 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
update()
chrome.contextMenus.update(
id: string | number,
updateProperties: object,
callback?: function,
)
更新先前建立的內容選單項目。
參數
-
id
string | number
要更新的項目 ID。
-
updateProperties
物件
要更新的屬性。接受與
contextMenus.create
函式相同的值。-
已勾選
布林值 (選用)
-
情境
[ContextType, ...ContextType[]] 選用
-
documentUrlPatterns
string[] 選填
-
已啟用
布林值 (選用)
-
parentId
string | number 選填
要設為這個項目父項的項目 ID。注意:您無法將項目設為其所屬子系的子項。
-
targetUrlPatterns
string[] 選填
-
title
字串 選用
-
類型
ItemType 選用
-
顯示
布林值 (選用)
Chrome 62 以上版本是否在選單中顯示項目。
-
onclick
void optional
onclick
函式如下所示:(info: OnClickData, tab: Tab) => {...}
-
資訊Chrome 44 以上版本
-
分頁
Tab 鍵
Chrome 44 以上版本發生點擊的分頁詳細資料。平台應用程式沒有這個參數。
-
-
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 123 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
活動
onClicked
chrome.contextMenus.onClicked.addListener(
callback: function,
)
點選內容選單項目時觸發。
參數
-
回呼
功能
callback
參數如下所示:(info: OnClickData, tab?: tabs.Tab) => void
-
資訊
-
分頁
tabs.Tab 選用
-