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」を除く他のすべてのコンテキストの組み合わせと同等です。「ランチャー」context はアプリでのみサポートされており、ランチャー、タスクバー、ドックなどでアプリのアイコンをクリックしたときに表示されるコンテキスト メニューにメニュー項目を追加するために使用されます。プラットフォームによっては、ランチャーのコンテキスト メニューで実際にサポートされている機能が制限される場合があります。

列挙型

"all"

"ページ"

"frame"

"selection"

"リンク"

編集可能

"image"

「動画」

"audio"

「ランチャー」

"browser_action"

"page_action"

"action"

CreateProperties

Chrome 123 以降

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

プロパティ

  • ON

    ブール値（省略可）

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

  • コンテキスト

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

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

  • documentUrlPatterns

    文字列 [] 省略可

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

  • 有効

    ブール値（省略可）

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

  • id

    文字列（省略可）

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

  • parentId

    string |数値（省略可）

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

  • targetUrlPatterns

    文字列 [] 省略可

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

  • title

    文字列（省略可）

    アイテムに表示するテキスト。type が separator である場合を除き、これは必須です。コンテキストが selection の場合、文字列内で %s を使用して、選択したテキストを表示します。たとえば、このパラメータの値が「Translate '%s'」の場合、宛先: 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

    ブール値（省略可）

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

  • 編集可能

    ブール値

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

  • frameId

    数値（省略可）

    Chrome 51 以降

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

  • frameUrl

    文字列（省略可）

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

  • linkUrl

    文字列（省略可）

    要素がリンクの場合は、その要素が指す URL。

  • mediaType

    文字列（省略可）

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

  • menuItemId

    string |数値

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

  • pageUrl

    文字列（省略可）

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

  • parentMenuItemId

    string |数値（省略可）

    クリックされたアイテムの親 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

    関数（省略可）

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

    () => void

戻り値

  • 数値 |文字列

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

remove()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.contextMenus.remove(
  menuItemId: string | number,
  callback?: function,
)

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

パラメータ

  • menuItemId

    string |数値

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

  • callback

    関数（省略可）

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

    () => void

戻り値

  • 約束 <void>

    Chrome 123 以降

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

removeAll()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.contextMenus.removeAll(
  callback?: function,
)

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

パラメータ

  • callback

    関数（省略可）

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

    () => void

戻り値

  • 約束 <void>

    Chrome 123 以降

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

update()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.contextMenus.update(
  id: string | number,
  updateProperties: object,
  callback?: function,
)

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

パラメータ

  • id

    string |数値

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

  • updateProperties

    オブジェクト

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

    • ON

      ブール値（省略可）

    • コンテキスト

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

    • documentUrlPatterns

      文字列 [] 省略可

    • 有効

      ブール値（省略可）

    • parentId

      string |数値（省略可）

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

    • targetUrlPatterns

      文字列 [] 省略可

    • title

      文字列（省略可）

    • type

      ItemType（省略可）

    • 表示

      ブール値（省略可）

      Chrome 62 以降

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

    • onclick

      void（省略可）

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

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

      • 情報

        OnClickData

        Chrome 44 以降
      • タブ

        Tab

        Chrome 44 以降

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

  • callback

    関数（省略可）

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

    () => void

戻り値

  • 約束 <void>

    Chrome 123 以降

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

イベント

onClicked

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

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

パラメータ