chrome.contextMenus

説明

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

権限

contextMenus

API を使用するには、拡張機能のマニフェストで "contextMenus" 権限を宣言する必要があります。また、メニュー項目の横に表示する 16×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 フィールドを指定します。

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

例

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

型

ContextType

Chrome 44 以降

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

列挙型

"all"

"page"

"frame"

"selection"

"link"

"editable"

"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 optional

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

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

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

    • 情報

      OnClickData

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

    • タブ

      Tab

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

ItemType

Chrome 44 以降

メニュー項目のタイプ。

列挙型

"normal"

"checkbox"

"radio"

"separator"

OnClickData

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

プロパティ

  • ON

    ブール値（省略可）

    クリック後のチェックボックスまたはラジオ項目の状態を示すフラグ。

  • 編集可能

    ブール値

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

  • frameId

    number 省略可

    Chrome 51 以降

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

  • frameUrl

    文字列 省略可

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

  • linkUrl

    文字列 省略可

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

  • mediaType

    文字列 省略可

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

  • menuItemId

    string | number

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

  • pageUrl

    文字列 省略可

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

  • parentMenuItemId

    文字列 | 数値 省略可

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

  • selectionText

    文字列 省略可

    コンテキスト選択のテキスト（ある場合）。

  • srcUrl

    文字列 省略可

    「src」URL を含む要素に存在します。

  • wasChecked

    ブール値（省略可）

    クリック前のチェックボックスまたはラジオ項目の状態を示すフラグ。

プロパティ

ACTION_MENU_TOP_LEVEL_LIMIT

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

値

6

メソッド

create()

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

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

パラメータ

  • createProperties

    CreateProperties

  • callback

    関数 省略可

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

    () => void

戻り値

  • number | string

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

remove()

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

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

パラメータ

  • menuItemId

    string | number

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

戻り値

  • Promise<void>

    Chrome 123 以降

removeAll()

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

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

戻り値

  • Promise<void>

    Chrome 123 以降

update()

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

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

パラメータ

  • id

    string | number

    更新するアイテムの ID。

  • updateProperties

    オブジェクト

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

    • ON

      ブール値（省略可）

    • コンテキスト

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

    • documentUrlPatterns

      string[] 省略可

    • 有効

      ブール値（省略可）

    • parentId

      文字列 | 数値 省略可

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

    • targetUrlPatterns

      string[] 省略可

    • title

      文字列 省略可

    • type

      ItemType 省略可

    • 表示

      ブール値（省略可）

      Chrome 62 以降

      メニューに項目が表示されるかどうか。

    • onclick

      void optional

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

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

      • 情報

        OnClickData

        Chrome 44 以降
      • タブ

        Tab

        Chrome 44 以降

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

戻り値

  • Promise<void>

    Chrome 123 以降

イベント

onClicked

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

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

パラメータ