commands
| 型 | Object |
|---|---|
| 必須 | いいえ |
| マニフェストバージョン | 2 以上 |
| 例 |
json |
commands キーを使うと、拡張機能用のキーボードショートカットを 1 つ以上定義できます。
それぞれのショートカットは、名前、キーの組み合わせ、説明で定義されます。拡張機能の manifest.json でコマンドを定義した後、commands API で関連付けられたキーの組み合わせを待ち受けできます。
構文
commands キーはオブジェクトで、それぞれのショートカットはそのプロパティです。プロパティ名はショートカットの名前です。
それぞれのショートカットの値は最大 2 つのプロパティを持つオブジェクトです。
suggested_key省略可: ショートカットを有効にするキーの組み合わせです。description省略可: ショートカットの機能を説明する文字列です。
suggested_key プロパティはオブジェクトで、次のプロパティを 0 個以上持ちます(値はすべて文字列です)。
"default""mac""linux""windows""chromeos""android""ios"
各プロパティの値は、そのプラットフォームでのコマンドのキーボードショートカットです。キーを + で区切った文字列で指定します。"default" の値は、明示的に指定されていないすべてのプラットフォームで使用されます。"default" がない場合、ユーザーまたは commands.update API が設定しない限り、明示的に指定されていないプラットフォームではショートカットはありません。
例えば:
"commands": {
"toggle-feature": {
"suggested_key": {
"default": "Alt+Shift+U",
"linux": "Ctrl+Shift+U"
},
"description": "Send a 'toggle-feature' event to the extension"
},
"do-another-thing": {
"suggested_key": {
"default": "Ctrl+Shift+Y"
}
},
"do-something-else": {
"suggested_key": {
"linux": "Ctrl+Shift+P"
}
},
"do-nothing-yet": {}
}
この JSON は、次のショートカットを定義します。
"toggle-feature"は Linux では Ctrl + Shift + U、その他のプラットフォームでは Alt + Shift + U で実行されます。"do-another-thing"はすべてのプラットフォームで Ctrl + Shift + Y で実行されます。"do-something-else"は Linux でのみ Ctrl + Shift + P で実行され、その他のプラットフォームではデフォルトのショートカットはありません。"do-nothing-yet"はキーボードショートカットを設定しませんが、ユーザーまたはcommands.updateAPI がショートカットを設定できるようにします。
次のようなコードでコマンドを待ち受けできます。この例では "toggle-feature" コマンドを待ち受けします。
browser.commands.onCommand.addListener(function (command) {
if (command === "toggle-feature") {
console.log("Toggling the feature!");
}
});
特殊なショートカット
デフォルトの動作を持つ特殊なショートカットが 4 つあります。これらのショートカットでは、commands.onCommand イベントは発生しません。
_execute_browser_action:browserActionAPI で作成された、またはmanifest.jsonのbrowser_actionキーで指定されたツールバーボタンのクリックと同じように動作します。_execute_action:actionAPI で作成された、またはmanifest.jsonのactionキーで指定されたツールバーボタンのクリックと同じように動作します。_execute_page_action:pageActionAPI で作成された、またはmanifest.jsonのpage_actionキーで指定されたアドレスバーのボタンのクリックと同じように動作します。_execute_sidebar_action:manifest.jsonのsidebar_actionキーで指定された拡張機能のサイドバーを開きます。
これらの特殊なショートカットが利用できるかどうかは、マニフェストのバージョンとブラウザーによって異なります。
| マニフェスト V2 | マニフェスト V3 | |
|---|---|---|
_execute_browser_action |
はい | いいえ |
_execute_action |
いいえ | はい |
_execute_page_action |
はい | Firefox のみ |
_execute_sidebar_action |
Firefox のみ | Firefox のみ |
メモ:
拡張機能を Manifest V2 から V3 に移行するとき、ユーザーが _execute_browser_action コマンドのショートカットを変更している場合、その変更は _execute_action コマンドに自動的に引き継がれます。この機能は Chrome 111 と Firefox 127 で実装されました。
例えば、これはブラウザーアクションをクリックするキーの組み合わせを定義します:
"commands": {
"_execute_browser_action": {
"suggested_key": {
"default": "Ctrl+Shift+Y"
}
}
}
ショートカットの値
ショートカットキーには2つのフォーマットがあります。キーの組み合わせとメディアキーです。
キーの組み合わせ
メモ:
Mac では "Ctrl" は "Command" として解釈されます。実際に "Ctrl" が必要な場合は、"MacCtrl" を指定してください。
キーの組み合わせは 2 つまたは 3 つのキーからなります。
- 修飾子(ファンクションキーの場合を除き必須)。
"Ctrl"、"Alt"、"Command"、"MacCtrl"のいずれかです。 - 第 2 修飾子(任意)。指定する場合は
"Shift"、または(Firefox 63 以降では)"Ctrl"、"Alt"、"Command"、"MacCtrl"のいずれかでなければなりません。主修飾子と同じ修飾子は指定できません。 - キー(必須)。次のいずれかです。
-
A~Zの文字 -
0~9の数字 -
ファンクションキー
F1~F12メモ: Firefox 135 以降では、ユーザーは 拡張機能のショートカットを管理(英語) から、
F13~F19キーを拡張機能に割り当てることができます。拡張機能はマニフェストファイルではこれらのキーを割り当てられませんが、commands.updateでは割り当てられます。 -
Comma、Period、Home、End、PageUp、PageDown、Space、Insert、Delete、Up、Down、Left、Right
-
キーは、上記の順序でキー値を + で区切った文字列として指定します。例えば、"Ctrl+Shift+Z" のようにします。
キーの組み合わせがブラウザー(例えば "Ctrl+P")や既存のアドオンですでに使用されている場合、その組み合わせを上書きすることはできません。定義することはできますが、ユーザーがその組み合わせを押してもイベントハンドラーは呼び出されません。
メディアキー
あるいは、ショートカットキーは次のいずれかでも指定できます:
"MediaNextTrack""MediaPlayPause""MediaPrevTrack""MediaStop"
ショートカットの更新
Firefox では、拡張機能から commands.update() を使ってショートカットキーの設定を更新できます。ユーザーは about:addons の拡張機能のショートカットを管理(英語) でショートカットを変更できます。この操作はこの動画(英語)で示されています。拡張機能からは commands.openShortcutSettings() を使ってこの設定を開けます。
Chrome では、拡張機能からプログラムでショートカットキーを更新することはできません。ユーザーは chrome://extensions/shortcuts でショートカットを変更できます。このページは tabs.create() を使って開けます。
Safari は拡張機能によるショートカットキーのプログラムでの変更に対応していません。Safari 26 以降では、ユーザーが Safari の拡張機能設定でショートカットを変更できます。
例
既定値だけを使って単一のショートカットを定義するには:
"commands": {
"toggle-feature": {
"suggested_key": {
"default": "Ctrl+Shift+Y"
},
"description": "Send a 'toggle-feature' event"
}
}
2つのショートカットを定義し、1つはプラットフォーム固有のキーの組み合わせとするには:
"commands": {
"toggle-feature": {
"suggested_key": {
"default": "Alt+Shift+U",
"linux": "Ctrl+Shift+U"
},
"description": "Send a 'toggle-feature' event"
},
"do-another-thing": {
"suggested_key": {
"default": "Ctrl+Shift+Y"
}
}
}