説明
Google Chrome のコンテキスト メニューにアイテムを追加するには、chrome.contextMenus
API を使用します。画像、ハイパーリンク、ページなど、コンテキスト メニューに追加するオブジェクトの種類を選択できます。
権限
contextMenus
使用量
コンテキスト メニュー項目は、file:// URL や chrome:// URL を含むドキュメント(またはドキュメント内のフレーム)に表示できます。項目を表示できるドキュメントを制御するには、create()
メソッドまたは update()
メソッドを呼び出すときに documentUrlPatterns フィールドを指定します。
コンテキスト メニュー項目は必要な数だけ作成できますが、拡張機能の複数の項目が同時に表示される場合は、自動的に 1 つの親メニューにまとめられます。
マニフェスト
API を使用するには、拡張機能のマニフェストで「contextMenus」権限を宣言する必要があります。また、メニュー項目の横に表示される 16x16 ピクセルのアイコンを指定する必要があります。次に例を示します。
{
"name": "My extension",
...
"permissions": [
"contextMenus"
],
"icons": {
"16": "icon-bitty.png",
"48": "icon-small.png",
"128": "icon-large.png"
},
...
}
例
この API を試すには、chrome-extension-samples リポジトリから contextMenus API の例をインストールしてください。
型
ContextType
メニューが表示されるさまざまなコンテキスト。「all」を指定すると、「launcher」を除いて、他のすべてのコンテキストの組み合わせと同じになります。「ランチャー」のコンテキストはアプリでのみサポートされ、ランチャー / タスクバー / ドックなどでアプリアイコンをクリックしたときに表示されるコンテキスト メニューにメニュー項目を追加するために使用されます。プラットフォームによって、ランチャーのコンテキスト メニューで実際にサポートされている内容に制限が適用される場合があります。
列挙型
"frame"
"selection"
"image"
"audio"
"browser_action"
"action"
CreateProperties
新しいコンテキスト メニュー項目のプロパティ。
プロパティ
-
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) => {...}
-
情報
クリックされたアイテムに関する情報と、クリックが発生した状況。
-
タブ
クリックが発生したタブの詳細。このパラメータは、プラットフォーム アプリには存在しません。
-
ItemType
メニュー項目のタイプ。
列挙型
"normal"
"checkbox"
"separator"
OnClickData
コンテキスト メニュー項目がクリックされたときに送信される情報。
プロパティ
-
ON
ブール値(省略可)
チェックボックスまたはラジオボタンがクリックされた後の状態を示すフラグ。
-
編集可能
boolean
要素が編集可能かどうかを示すフラグ(テキスト入力、テキスト領域など)。
-
frameId
number(省略可)
Chrome 51 以降コンテキスト メニューがクリックされた要素のフレームの ID(フレーム内に存在する場合)。
-
frameUrl
string(省略可)
コンテキスト メニューがクリックされた要素のフレームの URL(フレーム内に存在する場合)。
-
linkUrl
string(省略可)
要素がリンクの場合は、その要素が参照する URL。
-
mediaType
string(省略可)
「image」、「video」、「audio」のいずれか(コンテキスト メニューがこれらのタイプの要素で有効になっている場合)。
-
文字列 | 数値
クリックされたメニュー項目の ID。
-
pageUrl
string(省略可)
メニュー項目がクリックされたページの URL。現在のページがないコンテキスト(ランチャーのコンテキスト メニューなど)でクリックが発生した場合、このプロパティは設定されません。
-
parentMenuItemId
string | number 省略可
クリックされたアイテムの親 ID(ある場合)。
-
selectionText
string(省略可)
コンテキスト選択のテキスト(存在する場合)。
-
srcUrl
string(省略可)
「src」URL を持つ要素に存在します。
-
wasChecked
ブール値(省略可)
チェックボックスまたはラジオボタンがクリックされる前の状態を示すフラグ。
プロパティ
ACTION_MENU_TOP_LEVEL_LIMIT
拡張機能の操作コンテキスト メニューに追加できる最上位の拡張機能アイテムの最大数。この上限を超えるアイテムは無視されます。
値
6
メソッド
create()
chrome.contextMenus.create(
createProperties: CreateProperties,
callback?: function,
)
新しいコンテキスト メニュー項目を作成します。作成中にエラーが発生した場合、作成コールバックが呼び出されるまで検出されないことがあります。詳細は runtime.lastError
にあります。
パラメータ
-
createProperties
-
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
戻り値
-
数値 | 文字列
新しく作成されたアイテムの ID。
remove()
chrome.contextMenus.remove(
menuItemId: string | number,
callback?: function,
)
コンテキスト メニュー項目を削除します。
パラメータ
-
文字列 | 数値
削除するコンテキスト メニュー項目の ID。
-
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
戻り値
-
Promise<void>
Chrome 123 以降Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。
removeAll()
chrome.contextMenus.removeAll(
callback?: function,
)
この拡張機能によって追加されたすべてのコンテキスト メニュー項目を削除します。
パラメータ
-
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
戻り値
-
Promise<void>
Chrome 123 以降Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。
update()
chrome.contextMenus.update(
id: string | number,
updateProperties: object,
callback?: function,
)
以前に作成したコンテキスト メニュー項目を更新します。
パラメータ
-
id
文字列 | 数値
更新する商品アイテムの 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) => {...}
-
情報Chrome 44 以降
-
タブChrome 44 以降
クリックが発生したタブの詳細。このパラメータは、プラットフォーム アプリには存在しません。
-
-
-
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
戻り値
-
Promise<void>
Chrome 123 以降Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。
イベント
onClicked
chrome.contextMenus.onClicked.addListener(
callback: function,
)
コンテキスト メニュー項目がクリックされると呼び出されます。
パラメータ
-
callback
機能
callback
パラメータは次のようになります。(info: OnClickData, tab?: tabs.Tab) => void
-
情報
-
タブ
tabs.Tab 省略可
-