chrome.contextMenus

説明

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

権限

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:// URL や chrome:// URL を含むドキュメント（またはドキュメント内のフレーム）に表示できます。項目を表示できるドキュメントを制御するには、create() メソッドまたは update() メソッドを呼び出すときに documentUrlPatterns フィールドを指定します。

コンテキスト メニュー項目は必要な数だけ作成できますが、拡張機能の複数の項目が同時に表示される場合は、自動的に 1 つの親メニューにまとめられます。

例

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

型

ContextType

Chrome 44 以降

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

列挙型

"frame"

"selection"

"image"

"audio"

"browser_action"

"action"

CreateProperties

Chrome 123 以降

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

プロパティ

  • ON

    ブール値（省略可）

    チェックボックスまたはラジオボタンの初期状態: 選択中の場合は true、未選択の場合は false。1 つのグループで選択できるラジオボタンは一度に 1 つのみです。

  • コンテキスト

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

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

  • documentUrlPatterns

    string[] 省略可

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

  • 有効

    ブール値（省略可）

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

  • id

    string（省略可）

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

  • parentId

    string|number（省略可）

    親メニュー アイテムの ID。これにより、アイテムは以前に追加されたアイテムの子になります。

  • targetUrlPatterns

    string[] 省略可

    documentUrlPatterns と同様に、img タグ、audio タグ、video タグの src 属性と、a タグの href 属性に基づいてフィルタします。

  • title

    string（省略可）

    アイテムに表示するテキストです。type が separator である場合を除き、必須です。コンテキストが selection の場合は、文字列内で %s を使用して、選択したテキストを表示します。たとえば、このパラメータの値が「'%s' をピッグラテン語に翻訳」で、ユーザーが「クール」という単語を選択した場合、選択のコンテキスト メニュー項目は「「クール」をピッグラテン語に翻訳」となります。

  • type

    ItemType 省略可

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

  • 表示

    ブール値（省略可）

    アイテムがメニューに表示されるかどうか。

  • onclick

    void 省略可

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

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

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

    • 情報

      OnClickData

      クリックされたアイテムに関する情報と、クリックが発生した状況。

    • タブ

      Tab

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

ItemType

Chrome 44 以降

メニュー項目のタイプ。

列挙型

"normal"

"checkbox"

"separator"

OnClickData

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

プロパティ

  • ON

    ブール値（省略可）

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

  • 編集可能

    boolean

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

  • frameId

    number（省略可）

    Chrome 51 以降

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

  • frameUrl

    string（省略可）

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

  • linkUrl

    string（省略可）

    要素がリンクの場合は、その要素が参照する URL。

  • mediaType

    string（省略可）

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

  • menuItemId

    string|number

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

  • pageUrl

    string（省略可）

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

  • parentMenuItemId

    string|number（省略可）

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

  • selectionText

    string（省略可）

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

  • srcUrl

    string（省略可）

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

  • wasChecked

    ブール値（省略可）

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

プロパティ

ACTION_MENU_TOP_LEVEL_LIMIT

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

値

6

Methods

create()

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

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

パラメータ

  • createProperties

    CreateProperties

  • callback

    関数（省略可）

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

    ()=>void

戻り値

  • number|string

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

remove()

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

コンテキスト メニュー項目を削除します。

パラメータ

  • menuItemId

    string|number

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

  • callback

    関数（省略可）

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

    ()=>void

戻り値

  • Promise<void>

    Chrome 123 以降

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

removeAll()

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

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

パラメータ

  • callback

    関数（省略可）

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

    ()=>void

戻り値

  • Promise<void>

    Chrome 123 以降

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

update()

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

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

パラメータ

  • id

    string|number

    更新する商品アイテムの ID。

  • updateProperties

    オブジェクト

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

    • ON

      ブール値（省略可）

    • コンテキスト

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

    • documentUrlPatterns

      string[] 省略可

    • 有効

      ブール値（省略可）

    • parentId

      string|number（省略可）

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

    • targetUrlPatterns

      string[] 省略可

    • title

      string（省略可）

    • type

      ItemType 省略可

    • 表示

      ブール値（省略可）

      Chrome 62 以降

      アイテムがメニューに表示されるかどうか。

    • onclick

      void 省略可

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

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

      • 情報

        OnClickData

        Chrome 44 以降
      • タブ

        Tab

        Chrome 44 以降

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

  • callback

    関数（省略可）

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

    ()=>void

戻り値

  • Promise<void>

    Chrome 123 以降

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

イベント

onClicked

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

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

パラメータ