chrome.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，請從 chrome-extension-samples 存放區安裝 contextMenus API 範例。

類型

ContextType

Chrome 44 以上版本

選單可顯示的不同情境。除了「launcher」以外，指定「all」等同於所有其他結構定義的組合。「啟動器」內容僅適用於應用程式，可用來將選單項目加入至點選啟動器/taskbar/dock 等應用程式圖示時顯示的內容選單。不同平台可能會對啟動器內容選單實際支援的功能有所限制。

列舉

"selection"

"browser_action"

"page_action"

CreateProperties

Chrome 123 以上版本

新內容選單項目的屬性。

屬性

  • 已勾選

    布林值 (選用)

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

    • 資訊

      OnClickData

      點選的項目和點擊所在環境的相關資訊。

    • 分頁

      Tab 鍵

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

ItemType

Chrome 44 以上版本

選單項目的類型。

列舉

OnClickData

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

屬性

  • 已勾選

    布林值 (選用)

    指出核取方塊或圓形按鈕在點選後狀態的標記。

  • 可編輯

    boolean

    此標記表示元素是否可以編輯 (文字輸入、文字區域等)。

  • frameId

    數字 選填

    Chrome 51 以上版本

    獲點擊內容選單的元素頁框 ID (如果元素是在頁框中)。

  • frameUrl

    字串 選用

    使用者點擊內容選單時所在頁框的網址 (如果元素是在頁框中)。

  • linkUrl

    字串 選用

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

  • mediaType

    字串 選用

    如果其中一種元素已啟用內容選單，請選取「圖片」、「影片」或「音訊」。

  • menuItemId

    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

    CreateProperties

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • number|string

    新建立項目的 ID。

remove()

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

移除內容選單項目。

參數

  • menuItemId

    string|number

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

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 123 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

removeAll()

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

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

參數

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 123 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

update()

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

      • 資訊

        OnClickData

        Chrome 44 以上版本
      • 分頁

        Tab 鍵

        Chrome 44 以上版本

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

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 123 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

活動

onClicked

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

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

參數