chrome.contextMenus

説明

chrome.contextMenus API を使用して、Google Chrome のコンテキスト メニューにアイテムを追加します。コンテキスト メニューの追加を適用するオブジェクトの種類（画像、ハイパーリンク、ページなど）を選択できます。

権限

contextMenus

API を使用するには、拡張機能のマニフェストで "contextMenus" 権限を宣言する必要があります。また、メニュー項目の横に表示する 16 x 16 ピクセルのアイコンを指定する必要があります。次に例を示します。

{
  "name": "My extension",
  ...
  "permissions": [
    "contextMenus"
  ],
  "icons": {
    "16": "icon-bitty.png",
    "48": "icon-small.png",
    "128": "icon-large.png"
  },
  ...
}

コンセプトと使用方法

コンテキスト メニュー アイテムは、file:// または chrome:// の URL を持つドキュメント（またはドキュメント内のフレーム）に表示できます。アイテムを表示できるドキュメントを制御するには、create() メソッドまたは update() メソッドを呼び出すときに documentUrlPatterns フィールドを指定します。

コンテキスト メニュー アイテムは必要に応じていくつでも作成できますが、拡張機能の複数のアイテムが同時に表示される場合は、自動的に 1 つの親メニューにまとめられます。

例

この API を試すには、chrome-extension-samples リポジトリから contextMenus API の例をインストールします。

型

ContextType

Chrome 44 以降

メニューが表示されるさまざまなコンテキスト。「all」を指定すると、「launcher」を除く他のすべてのコンテキストが組み合わせられます。「ランチャー」コンテキストはアプリでのみサポートされ、ランチャー / タスクバー / ドックなどでアプリアイコンをクリックしたときに表示されるコンテキスト メニューにメニュー項目を追加するために使用されます。プラットフォームによって、ランチャーのコンテキスト メニューで実際にサポートされる内容に制限が設けられている場合があります。

列挙型

「all」

「page」

「frame」

「選択」

「link」

「編集可能」

「image」

「video」

「audio」

「launcher」

"browser_action"

"page_action"

「action」

CreateProperties

Chrome 123 以降

新しいコンテキスト メニュー項目のプロパティ。

プロパティ

  • ON

    ブール値（省略可）

    チェックボックスまたはラジオボタンの初期状態: 選択されている場合は true、選択されていない場合は false。特定のグループで一度に選択できるラジオボタンは 1 つだけです。

  • コンテキスト

    [ContextType, ...ContextType[]] 省略可

    このメニュー項目が表示されるコンテキストのリスト。デフォルトは ['page'] です。

  • documentUrlPatterns

    string[] 省略可

    指定されたパターンのいずれかに一致する URL のドキュメントまたはフレームにのみ適用されるように項目を制限します。パターン形式の詳細については、一致パターンをご覧ください。

  • 有効

    ブール値（省略可）

    このコンテキスト メニュー項目が有効か無効か。デフォルトは true です。

  • id

    文字列（省略可）

    このアイテムに割り当てる一意の ID。イベントページでは必須です。この拡張機能の別の ID と同じにすることはできません。

  • parentId

    文字列 | 数値（省略可）

    親メニュー項目の ID。これにより、この項目は以前に追加した項目の子になります。

  • targetUrlPatterns

    string[] 省略可

    documentUrlPatterns と同様に、img、audio、video タグの src 属性と、a タグの href 属性に基づくフィルタ。

  • title

    文字列（省略可）

    項目に表示するテキスト。type が separator でない限り、必須です。コンテキストが selection の場合は、文字列内で %s を使用して、選択したテキストを表示します。たとえば、このパラメータの値が「Translate '%s' to Pig Latin」で、ユーザーが「cool」という単語を選択した場合、選択した単語のコンテキスト メニュー項目は「Translate 'cool' to Pig Latin」になります。

  • type

    ItemType 省略可

    メニュー項目のタイプ。デフォルトは normal です。

  • 表示

    ブール値（省略可）

    メニューにアイテムを表示するかどうか。

  • onclick

    void 省略可

    メニュー項目がクリックされたときに呼び出される関数。これは Service Worker 内では使用できません。代わりに、contextMenus.onClicked のリスナーを登録する必要があります。

    onclick 関数は次のようになります。 

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

    • 情報

      OnClickData

      クリックされたアイテムと、クリックされたコンテキストに関する情報。

    • タブ

      Tab

      クリックが発生したタブの詳細。このパラメータは、プラットフォーム アプリには存在しません。

ItemType

Chrome 44 以降

メニュー項目のタイプ。

列挙型

「normal」

"checkbox"

「radio」

「separator」

OnClickData

コンテキスト メニュー項目がクリックされたときに送信される情報。

プロパティ

  • ON

    ブール値（省略可）

    チェックボックスまたはラジオボタンがクリックされた後の状態を示すフラグ。

  • 編集可能

    ブール値

    要素が編集可能かどうかを示すフラグ（テキスト入力、textarea など）。

  • frameId

    number（省略可）

    Chrome 51 以降

    コンテキスト メニューがクリックされた要素のフレームの ID（フレーム内にあった場合）。

  • frameUrl

    文字列（省略可）

    コンテキスト メニューがクリックされた要素のフレームの URL（フレーム内にあった場合）。

  • linkUrl

    文字列（省略可）

    要素がリンクの場合は、リンク先の URL。

  • mediaType

    文字列（省略可）

    これらのタイプの要素でコンテキスト メニューが有効になっている場合は、「image」、「video」、「audio」のいずれか。

  • menuItemId

    文字列 | 数値

    クリックされたメニュー項目の ID。

  • pageUrl

    文字列（省略可）

    メニュー項目がクリックされたページの URL。現在のページがないコンテキスト（ランチャーのコンテキスト メニューなど）でクリックが発生した場合、このプロパティは設定されません。

  • parentMenuItemId

    文字列 | 数値（省略可）

    クリックされたアイテムの親 ID（存在する場合）。

  • selectionText

    文字列（省略可）

    コンテキスト選択のテキスト（該当する場合）。

  • srcUrl

    文字列（省略可）

    「src」URL を持つ要素に存在します。

  • wasChecked

    ブール値（省略可）

    チェックボックスまたはラジオボタンがクリックされる前の状態を示すフラグ。

プロパティ

ACTION_MENU_TOP_LEVEL_LIMIT

拡張機能のアクション コンテキスト メニューに追加できる最上位の拡張機能アイテムの最大数。この上限を超えるアイテムは無視されます。

値

6

メソッド

create()

chrome.contextMenus.create(
  createProperties: CreateProperties,
  callback?: function,
)

新しいコンテキスト メニュー アイテムを作成します。作成中にエラーが発生した場合、作成コールバックがトリガーされるまで検出されないことがあります。詳細は runtime.lastError に含まれます。

パラメータ

  • createProperties

    CreateProperties

  • callback

    function 省略可

    callback パラメータは次のようになります。 

    () => void

戻り値

  • 数値 | 文字列

    新しく作成されたアイテムの ID。

remove()

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

コンテキスト メニュー アイテムを削除します。

パラメータ

  • menuItemId

    文字列 | 数値

    削除するコンテキスト メニュー項目の ID。

  • callback

    function 省略可

    callback パラメータは次のようになります。 

    () => void

戻り値

  • Promise<void>

    Chrome 123 以降

    Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

removeAll()

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

この拡張機能によって追加されたコンテキスト メニュー アイテムをすべて削除します。

パラメータ

  • callback

    function 省略可

    callback パラメータは次のようになります。 

    () => void

戻り値

  • Promise<void>

    Chrome 123 以降

    Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

update()

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

以前に作成したコンテキスト メニュー アイテムを更新します。

パラメータ

  • id

    文字列 | 数値

    更新するアイテムの ID。

  • updateProperties

    オブジェクト

    更新するプロパティ。contextMenus.create 関数と同じ値を受け入れます。

    • ON

      ブール値（省略可）

    • コンテキスト

      [ContextType, ...ContextType[]] 省略可

    • documentUrlPatterns

      string[] 省略可

    • 有効

      ブール値（省略可）

    • parentId

      文字列 | 数値（省略可）

      このアイテムの親にするアイテムの ID。注: アイテムを自身の子孫の子に設定することはできません。

    • targetUrlPatterns

      string[] 省略可

    • title

      文字列（省略可）

    • type

      ItemType 省略可

    • 表示

      ブール値（省略可）

      Chrome 62 以降

      メニューにアイテムを表示するかどうか。

    • onclick

      void 省略可

      onclick 関数は次のようになります。 

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

      • 情報

        OnClickData

        Chrome 44 以降
      • タブ

        Tab

        Chrome 44 以降

        クリックが発生したタブの詳細。このパラメータは、プラットフォーム アプリには存在しません。

  • callback

    function 省略可

    callback パラメータは次のようになります。 

    () => void

戻り値

  • Promise<void>

    Chrome 123 以降

    Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。

イベント

onClicked

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

コンテキスト メニュー項目がクリックされたときに呼び出されます。

パラメータ