說明
如要在 Google Chrome 的內容選單中新增項目,請使用 chrome.contextMenus
API。你可以選擇要在內容選單中新增的物件類型,例如圖片、超連結和頁面。
權限
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:// 網址如要控制檔案可以顯示在哪些文件,請指定
documentUrlPatterns
欄位。create()
update()
您可以視需要建立的內容選單項目數量沒有限制,但如果擴充功能含有多個內容選單項目, Google Chrome 會自動將項目收合為單一父項選單
範例
如要試用這個 API,請安裝 chrome-extension-samples 提供的 contextMenus API 範例 Cloud Storage 也提供目錄同步處理功能
類型
ContextType
選單可顯示的不同內容。指定「all」相當於「launcher」以外的所有背景資訊的組合。啟動器內容僅適用於應用程式,且可在點選啟動器/工作列/dock/等程式中的應用程式圖示時,在顯示的內容選單中新增選單項目。不同平台可能會對啟動器內容選單中實際支援的功能設有限制。
列舉
"all"
"網頁"
"框"
"selection"
"連結"
"editable"
"圖片"
"影片"
"音訊"
"launcher"
"browser_action"
"page_action"
"action"
CreateProperties
新內容選單項目的屬性。
屬性
-
已勾選
布林值 選填
核取方塊或圓形按鈕的初始狀態:已選取
true
代表未選取,false
代表未選取。指定群組內一次只能選取一個圓形按鈕。 -
情境
[ContextType, ...ContextType[]] 選用
會顯示此選單項目的內容清單。預設值為
['page']
。 -
documentUrlPatterns
string[] 選填
將項目限制為僅套用至網址符合其中一個指定模式的文件或頁框。如要進一步瞭解模式格式,請參閱比對模式。
-
已啟用
布林值 選填
這個內容選單項目為啟用或停用狀態。預設值為
true
。 -
id
string optional
要指派給這個項目的專屬 ID。活動頁面必須使用這個屬性。不得與這項擴充功能的其他 ID 相同。
-
parentId
string |編號 選填
父項選單項目的 ID;如此一來,該項目就會成為先前新增項目的子項。
-
targetUrlPatterns
string[] 選填
與
documentUrlPatterns
類似,篩選器是根據img
、audio
和video
標記的src
屬性以及a
標記的href
屬性進行篩選。 -
title
string optional
要在項目中顯示的文字;除非
type
為separator
,否則這是必填項目。當結構定義為selection
時,在字串中使用%s
即可顯示所選文字。例如,如果這個參數的值是「Translate '%s」CANNOT TRANSLATE當使用者選取「cool」一詞時,用於選取項目的內容選單項目是「Translate 'cool'」。Pig Latin 的密語。」 -
類型
ItemType 選用
選單項目的類型。預設值為
normal
。 -
顯示
布林值 選填
該項目是否顯示在選單中。
-
點擊
void optional
點選選單項目時呼叫的函式。這無法在 Service Worker 內使用;請改為註冊
contextMenus.onClicked
的事件監聽器。onclick
函式如下所示:(info: OnClickData, tab: Tab) => {...}
-
資訊
與點擊的項目及發生點擊情境相關的資訊。
-
分頁
發生點擊的分頁詳細資料。平台應用程式不提供這個參數。
-
ItemType
選單項目的類型。
列舉
"normal"
「核取方塊」
"電台"
"分隔符"
OnClickData
使用者點選內容選單項目時傳送的資訊。
屬性
-
已勾選
布林值 選填
此旗標代表按一下核取方塊或圓形按鈕項目後的狀態。
-
可編輯
布林值
此標記用於指出元素是否可編輯 (文字輸入內容、文字區域等)。
-
frameId
編號 選填
Chrome 51 以上版本使用者點選內容選單的元素影格 ID (如果位於頁框中)。
-
frameUrl
string optional
使用者點選內容選單的元素頁框網址 (如果位於頁框中)。
-
linkUrl
string optional
如果元素是連結,則會指向元素的網址。
-
mediaType
string optional
可以是「image」、「video」或「audio」其中之一是否在其中一個元素類型上啟用內容選單。
-
string |號碼
所點擊選單項目的 ID。
-
pageUrl
string optional
使用者點選選單項目的網頁網址。如果不是在沒有目前網頁 (例如在啟動器內容選單中) 發生點擊,系統就不會設定這項屬性。
-
parentMenuItemId
string |編號 選填
所點擊項目的父項 ID (如有)。
-
selectionText
string optional
情境選取項目的文字 (如果有的話)。
-
srcUrl
string optional
會顯示具有「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 |號碼
待移除內容選單項目的 ID。
-
回呼
函式 選用
callback
參數如下所示:() => void
傳回
-
承諾<void>
Chrome 123 以上版本Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
removeAll()
chrome.contextMenus.removeAll(
callback?: function,
)
移除由這個擴充功能新增的所有內容選單項目。
參數
-
回呼
函式 選用
callback
參數如下所示:() => void
傳回
-
承諾<void>
Chrome 123 以上版本Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
update()
chrome.contextMenus.update(
id: string | number,
updateProperties: object,
callback?: function,
)
更新先前建立的內容選單項目。
參數
-
id
string |號碼
要更新的項目 ID。
-
updateProperties
物件
要更新的屬性。接受的值與
contextMenus.create
函式相同。-
已勾選
布林值 選填
-
情境
[ContextType, ...ContextType[]] 選用
-
documentUrlPatterns
string[] 選填
-
已啟用
布林值 選填
-
parentId
string |編號 選填
要設為此項目父項的項目 ID。注意:您無法將項目設為其子系的子項。
-
targetUrlPatterns
string[] 選填
-
title
string optional
-
類型
ItemType 選用
-
顯示
布林值 選填
Chrome 62 以上版本該項目是否顯示在選單中。
-
點擊
void optional
onclick
函式如下所示:(info: OnClickData, tab: Tab) => {...}
-
資訊Chrome 44 以上版本
-
分頁Chrome 44 以上版本
發生點擊的分頁詳細資料。平台應用程式不提供這個參數。
-
-
-
回呼
函式 選用
callback
參數如下所示:() => void
傳回
-
承諾<void>
Chrome 123 以上版本Promise 適用於 Manifest V3 及以上版本,但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。
活動
onClicked
chrome.contextMenus.onClicked.addListener(
callback: function,
)
使用者點選內容選單項目時觸發。
參數
-
回呼
函式
callback
參數如下所示:(info: OnClickData, tab?: tabs.Tab) => void
-
資訊
-
分頁
tabs.Tab 選用
-