browser.contextMenus

說明

使用 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 成員的參考資訊。如需 API 使用說明，請參閱「建構內容選單」。

範例

如要試用這個 API，請從 chrome-extension-samples 存放區安裝 contextMenus API 範例。

類型

ContextType

Chrome 44 以上版本 瀏覽器。*自 Chrome 148 起

選單可能出現的不同情境。指定「all」等同於除了「launcher」和「tab」以外的所有其他情境組合。只有應用程式支援「啟動器」內容，可用於在點選啟動器/工作列/Dock 等位置的應用程式圖示時，將選單項目新增至顯示的內容選單。不同平台可能會對啟動器內容選單實際支援的內容設下限制。

列舉

"all"

"page"

"frame"

"selection"

"link"

"editable"

"image"

"video"

"audio"

"launcher"

"action"
適用於擴充功能動作 (工具列圖示) 的內容選單。

"tab"
適用於分頁列中分頁的內容選單。

CreateProperties

Chrome 123 以上版本 Chrome 148 以上版本支援 browser.*

新內容選單項目的屬性。

屬性

  • 已勾選

    布林值 選填

    核取方塊或圓形按鈕的初始狀態：true 表示已選取，false 表示未選取。在特定群組中，一次只能選取一個圓形按鈕。

  • contexts

    [ContextType, ...ContextType[]] 選填

    這個選單項目會顯示在哪些情境。預設值為 ['page']。

  • documentUrlPatterns

    string[] 選填

    限制項目僅套用至網址符合指定模式的文件或框架。如要進一步瞭解模式格式，請參閱「比對模式」。

  • 已啟用

    布林值 選填

    這個內容選單項目是否已啟用。預設值為 true。

  • id

    字串 選填

    要指派給這個項目的專屬 ID。活動網頁必須提供這項資訊。不得與這個擴充功能的其他 ID 相同。

  • parentId

    字串 | 數字 選填

    上層選單項目的 ID；這會使該項目成為先前新增項目的子項。

  • targetUrlPatterns

    string[] 選填

    與 documentUrlPatterns 類似，根據 img、audio 和 video 標記的 src 屬性，以及 a 標記的 href 屬性進行篩選。

  • title

    字串 選填

    項目中顯示的文字；除非 type 為 separator，否則這是必要欄位。如果情境是 selection，請在字串中使用 %s 顯示所選文字。舉例來說，如果這個參數的值是「將『%s』翻譯成兒童黑話」，而使用者選取了「cool」這個字，則所選內容的內容選單項目會是「將『cool』翻譯成兒童黑話」。

  • 類型

    ItemType 選填

    選單項目類型。預設值為 normal。

  • 顯示

    布林值 選填

    項目是否顯示在選單中。

  • onclick

    void 選填

    點選選單項目時回呼的函式。這項功能不適用於 Service Worker，請改為註冊 contextMenus.onClicked 的事件監聽器。

    onclick 函式如下所示： 

    (info: OnClickData, tab: Tab) => {...}

    • 資訊

      OnClickData

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

    • Tab 鍵

      Tab

      點擊發生時所在分頁的詳細資料。平台應用程式沒有這個參數。

ItemType

Chrome 44 以上版本 瀏覽器。*自 Chrome 148 起

選單項目類型。

列舉

"normal"

"checkbox"

"radio"

"separator"

OnClickData

點按內容選單項目時傳送的資訊。

屬性

  • 已勾選

    布林值 選填

    這個標記用於指出核取方塊或圓形按鈕項目在點選後的狀態。

  • 可編輯

    布林值

    標記，指出元素是否可編輯 (文字輸入、文字區域等)。

  • frameId

    數字 選填

    Chrome 51 以上版本 Chrome 148 以上版本為 browser.*

    點按內容選單的元素頁框 ID (如果位於頁框中)。

  • frameUrl

    字串 選填

    如果內容選單是在框架中點擊，則為元素框架的網址。

  • linkUrl

    字串 選填

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

  • mediaType

    字串 選填

    如果是在這類元素上啟用內容選單，則為「image」、「video」或「audio」其中之一。

  • menuItemId

    string | number

    獲得點擊的選單項目 ID。

  • pageUrl

    字串 選填

    使用者點選選單項目時所在的網頁網址。如果點擊事件發生在沒有目前頁面的情境 (例如啟動器內容選單)，則不會設定這個屬性。

  • parentMenuItemId

    字串 | 數字 選填

    所點擊項目的上層 ID (如有)。

  • selectionText

    字串 選填

    內容選取項目的文字 (如果有的話)。

  • srcUrl

    字串 選填

    如果元素含有「src」網址，就會顯示這個屬性。

  • wasChecked

    布林值 選填

    這個標記會指出核取方塊或圓形按鈕項目在點擊前的狀態。

屬性

ACTION_MENU_TOP_LEVEL_LIMIT

擴充功能動作內容選單中，可新增的頂層擴充功能項目數量上限。系統會忽略超出這項限制的所有項目。

值

6

方法

create()

browser.contextMenus.create(
  createProperties: CreateProperties,
  callback?: function,
): number | string

建立新的內容選單項目。如果建立期間發生錯誤，系統可能要等到建立回呼觸發後才會偵測到，詳細資料會顯示在 runtime.lastError 中。

參數

  • createProperties

    CreateProperties

  • callback

    函式 選填

    callback 參數如下： 

    () => void

傳回

  • number | string

    新建立項目的 ID。

remove()

browser.contextMenus.remove(
  menuItemId: string | number,
): Promise<void>

移除內容選單項目。

參數

  • menuItemId

    string | number

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

傳回

  • 承諾<void>

    Chrome 123 以上版本 Chrome 148 以上版本支援 browser.*

    在移除內容選單時解析。

removeAll()

browser.contextMenus.removeAll(): Promise<void>

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

傳回

  • 承諾<void>

    Chrome 123 以上版本 Chrome 148 以上版本支援 browser.*

    移除完成後，系統會解析。

update()

browser.contextMenus.update(
  id: string | number,
  updateProperties: object,
): Promise<void>

更新先前建立的內容選單項目。

參數

  • id

    string | number

    要更新的項目 ID。

  • updateProperties

    物件

    要更新的屬性。接受與 contextMenus.create 函式相同的值。

    • 已勾選

      布林值 選填

    • contexts

      [ContextType, ...ContextType[]] 選填

    • documentUrlPatterns

      string[] 選填

    • 已啟用

      布林值 選填

    • parentId

      字串 | 數字 選填

      要設為這個項目上層項目的 ID。注意：您無法將項目設為自身子系的子項。

    • targetUrlPatterns

      string[] 選填

    • title

      字串 選填

    • 類型

      ItemType 選填

    • 顯示

      布林值 選填

      Chrome 62+ 瀏覽器。*自 Chrome 148 起

      項目是否顯示在選單中。

    • onclick

      void 選填

      onclick 函式如下所示： 

      (info: OnClickData, tab: Tab) => {...}

      • 資訊

        OnClickData

        Chrome 44 以上版本 瀏覽器。*自 Chrome 148 起
      • Tab 鍵

        Tab

        Chrome 44 以上版本 瀏覽器。*自 Chrome 148 起

        點擊發生時所在分頁的詳細資料。平台應用程式沒有這個參數。

傳回

  • 承諾<void>

    Chrome 123 以上版本 Chrome 148 以上版本支援 browser.*

    在內容選單更新後解析。

事件

onClicked

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

點按內容選單項目時觸發。

參數