このページは Cloud Translation API によって翻訳されました。

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

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

値

メソッド

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,
)

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

パラメータ

callback

関数

callback パラメータは次のようになります。
```
(info: OnClickData, tab?: tabs.Tab) => void
```
- 情報
  
  OnClickData
- タブ
  
  tabs.Tab 省略可