chrome.contextMenus

說明

如要在 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

Chrome 44 以上版本

選單可顯示的不同內容。指定「all」相當於「launcher」以外的所有背景資訊的組合。啟動器內容僅適用於應用程式，且可在點選啟動器/工作列/dock/等程式中的應用程式圖示時，在顯示的內容選單中新增選單項目。不同平台可能會對啟動器內容選單中實際支援的功能設有限制。

列舉

"all"

"網頁"

"框"

"selection"

"連結"

"editable"

"圖片"

"影片"

"音訊"

"launcher"

"browser_action"

"page_action"

"action"

CreateProperties

Chrome 123 以上版本

新內容選單項目的屬性。

屬性

  • 已勾選

    布林值 選填

    核取方塊或圓形按鈕的初始狀態：已選取 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) => {...}

    • 資訊

      OnClickData

      與點擊的項目及發生點擊情境相關的資訊。

    • 分頁

      Tab 鍵

      發生點擊的分頁詳細資料。平台應用程式不提供這個參數。

ItemType

Chrome 44 以上版本

選單項目的類型。

列舉

"normal"

「核取方塊」

"電台"

"分隔符"

OnClickData

使用者點選內容選單項目時傳送的資訊。

屬性

  • 已勾選

    布林值 選填

    此旗標代表按一下核取方塊或圓形按鈕項目後的狀態。

  • 可編輯

    布林值

    此標記用於指出元素是否可編輯 (文字輸入內容、文字區域等)。

  • frameId

    編號 選填

    Chrome 51 以上版本

    使用者點選內容選單的元素影格 ID (如果位於頁框中)。

  • frameUrl

    string optional

    使用者點選內容選單的元素頁框網址 (如果位於頁框中)。

  • linkUrl

    string optional

    如果元素是連結，則會指向元素的網址。

  • mediaType

    string optional

    可以是「image」、「video」或「audio」其中之一是否在其中一個元素類型上啟用內容選單。

  • menuItemId

    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

    CreateProperties

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 數字 |字串

    新建立項目的 ID。

remove()

Promise 
chrome.contextMenus.remove(
  menuItemId: string | number,
  callback?: function,
)

移除內容選單項目。

參數

  • menuItemId

    string |號碼

    待移除內容選單項目的 ID。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 123 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

removeAll()

Promise 
chrome.contextMenus.removeAll(
  callback?: function,
)

移除由這個擴充功能新增的所有內容選單項目。

參數

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 123 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

update()

Promise 
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) => {...}

      • 資訊

        OnClickData

        Chrome 44 以上版本
      • 分頁

        Tab 鍵

        Chrome 44 以上版本

        發生點擊的分頁詳細資料。平台應用程式不提供這個參數。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 123 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

活動

onClicked

chrome.contextMenus.onClicked.addListener(
  callback: function,
)

使用者點選內容選單項目時觸發。

參數