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 以上版本

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

列舉

"all"

"page"

"frame"

"selection"

"link"

「editable」

"image"

"video"

"audio"

"launcher"

"browser_action"

"page_action"

"action"

CreateProperties

Chrome 123 以上版本

新內容選單項目的屬性。

屬性

  • 已勾選

    boolean 選填

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

  • 背景

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

    這個選單項目會顯示的內容清單。預設值為 ['page']。

  • documentUrlPatterns

    string[] 選填

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

  • 已啟用

    boolean 選填

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

  • id

    string 選填

    要指派給此項目的專屬 ID。這是活動網頁的必要項目。不得與此擴充功能的其他 ID 相同。

  • parentId

    字串 | 數字 選填

    父項選單項目的 ID，這會使該項目成為先前新增項目的子項。

  • targetUrlPatterns

    string[] 選填

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

  • title

    string 選填

    在項目中顯示的文字。除非 type 為 separator，否則此為必要屬性。如果結構定義為 selection，請在字串中使用 %s 顯示所選文字。舉例來說，如果這個參數的值是「Translate '%s' to Pig Latin」，而使用者選取「cool」這個字，則選取內容的內容選單項目會是「Translate 'cool' to Pig Latin」。

  • 類型

    ItemType 選填

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

  • 顯示

    boolean 選填

    項目是否會顯示在選單中。

  • onclick

    void 選填

    點選選單項目時會呼叫的回呼函式。這項功能無法在 Service Worker 中使用，您應該為 contextMenus.onClicked 註冊監聽器。

    onclick 函式如下所示： 

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

    • 資訊

      OnClickData

      點選的項目和點擊發生的背景資訊。

    • 分頁

      分頁

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

ItemType

Chrome 44 以上版本

選單項目的類型。

列舉

"normal"

"checkbox"

"radio"

"separator"

OnClickData

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

屬性

  • 已勾選

    boolean 選填

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

  • 可編輯

    布林值

    此標記可指出元素是否可編輯 (文字輸入、文字欄位等)。

  • frameId

    號碼 選填

    Chrome 51 以上版本

    點選內容選單的元素影格 ID (如果位於影格中)。

  • frameUrl

    string 選填

    點選內容選單的元素所在影格網址 (如果在影格中)。

  • linkUrl

    string 選填

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

  • mediaType

    string 選填

    如果內容選單是在上述任一類型的元素上啟用，則為「image」、「video」或「audio」之一。

  • menuItemId

    字串 | 數字

    已按下的選單項目 ID。

  • pageUrl

    string 選填

    點選選單項目的網頁網址。如果點擊發生在沒有目前網頁的情況下 (例如在啟動器內容選單中)，就不會設定這個屬性。

  • parentMenuItemId

    字串 | 數字 選填

    點選的項目父項 ID (如果有的話)。

  • selectionText

    string 選填

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

  • srcUrl

    string 選填

    適用於含有「src」網址的元素。

  • wasChecked

    boolean 選填

    此標記用於指出核取方塊或圓形按鈕在點選前所處的狀態。

屬性

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

    字串 | 數字

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

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 123 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

removeAll()

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

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

參數

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 123 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

update()

Promise 
chrome.contextMenus.update(
  id: string | number,
  updateProperties: object,
  callback?: function,
)

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

參數

  • id

    字串 | 數字

    要更新的商品 ID。

  • updateProperties

    物件

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

    • 已勾選

      boolean 選填

    • 背景

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

    • documentUrlPatterns

      string[] 選填

    • 已啟用

      boolean 選填

    • parentId

      字串 | 數字 選填

      要設為此商品父項的商品 ID。注意：您無法將項目設為其自身後代子項。

    • targetUrlPatterns

      string[] 選填

    • title

      string 選填

    • 類型

      ItemType 選填

    • 顯示

      boolean 選填

      Chrome 62 以上版本

      項目是否會顯示在選單中。

    • onclick

      void 選填

      onclick 函式如下所示： 

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

      • 資訊

        OnClickData

        Chrome 44 以上版本
      • 分頁

        分頁

        Chrome 44 以上版本

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

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 123 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

活動

onClicked

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

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

參數