説明
commands API を使用して、拡張機能でアクションをトリガーするキーボード ショートカットを追加します。たとえば、ブラウザ アクションを開くアクションや、拡張機能にコマンドを送信するアクションなどです。
マニフェスト
コンセプトと使用方法
Commands API を使用すると、拡張機能のデベロッパーは特定のコマンドを定義し、デフォルトのキーの組み合わせにバインドできます。拡張機能が受け入れる各コマンドは、拡張機能のマニフェストで "commands" オブジェクトのプロパティとして宣言する必要があります。
プロパティキーは、コマンドの名前として使用されます。コマンド オブジェクトには 2 つのプロパティを指定できます。
suggested_keyコマンドのデフォルトのキーボード ショートカットを宣言するオプション プロパティ。省略した場合、コマンドはバインド解除されます。このプロパティには、文字列またはオブジェクト値を指定できます。
文字列値: すべてのプラットフォームで使用されるデフォルトのキーボード ショートカットを指定します。
オブジェクト値を使用すると、拡張機能のデベロッパーはプラットフォームごとにキーボード ショートカットをカスタマイズできます。プラットフォーム固有のショートカットを指定する場合は、有効なオブジェクト プロパティは
default、chromeos、linux、mac、windowsです。
詳しくは、キーの組み合わせの要件をご覧ください。
descriptionコマンドの目的をユーザーに簡単に説明するために使用される文字列。この文字列は、拡張機能のキーボード ショートカット管理 UI に表示されます。説明は標準コマンドでは必須ですが、アクション コマンドでは無視されます。
拡張機能には多くのコマンドを設定できますが、候補として指定できるキーボード ショートカットは 4 つまでです。ユーザーは、chrome://extensions/shortcuts ダイアログからショートカットを手動で追加できます。
サポートされているキー
次のキーは、使用可能なコマンド ショートカットです。キーの定義では大文字と小文字が区別されます。大文字と小文字が正しくないキーを使用して拡張機能を読み込もうとすると、インストール時にマニフェストの解析エラーが発生します。
- アルファキー
A…Z- 数字キー
0…9- 標準のキー文字列
全般 -
Comma、Period、Home、End、PageUp、PageDown、Space、Insert、Delete矢印キー -
Up、Down、Left、Rightメディアキー -
MediaNextTrack、MediaPlayPause、MediaPrevTrack、MediaStop- 修飾キー文字列
Ctrl、Alt、Shift、MacCtrl（macOS のみ）、Command（macOS のみ）、Search（ChromeOS のみ）
キーの組み合わせの要件
拡張機能のコマンド ショートカットには、
CtrlまたはAltを含める必要があります。修飾子は、メディアキーと組み合わせて使用できません。
多くの macOS キーボードでは、
Altは Option キーを表します。macOS では、
CtrlまたはAltの代わりにCommandまたはMacCtrlを使用することもできます（次の箇条書きを参照）。
macOS では、
Ctrlは自動的にCommandに変換されます。Commandは、"mac"ショートカットで使用して、Command キーを明示的に参照することもできます。macOS で Ctrl キーを使用するには、
"mac"ショートカットを定義するときにCtrlをMacCtrlに置き換えます。別のプラットフォームの組み合わせで
MacCtrlを使用すると、検証エラーが発生し、拡張機能がインストールされなくなります。
Shiftは、すべてのプラットフォームで省略可能な修飾子です。Searchは ChromeOS 専用のオプションの修飾子です。特定のオペレーティング システムと Chrome のショートカット（ウィンドウ管理など）は、拡張機能のコマンド ショートカットよりも常に優先され、オーバーライドできません。
コマンド イベントを処理する
manifest.json:
{
"name": "My extension",
...
"commands": {
"run-foo": {
"suggested_key": {
"default": "Ctrl+Shift+Y",
"mac": "Command+Shift+Y"
},
"description": "Run \"foo\" on the current page."
},
"_execute_action": {
"suggested_key": {
"windows": "Ctrl+Shift+Y",
"mac": "Command+Shift+Y",
"chromeos": "Ctrl+Shift+U",
"linux": "Ctrl+Shift+J"
}
}
},
...
}
サービス ワーカーでは、onCommand.addListener を使用して、マニフェストで定義された各コマンドにハンドラをバインドできます。次に例を示します。
service-worker.js:
chrome.commands.onCommand.addListener((command) => {
console.log(`Command: ${command}`);
});
アクション コマンド
_execute_action（Manifest V3）、_execute_browser_action（Manifest V2）、_execute_page_action（Manifest V2）コマンドは、それぞれアクションのトリガー、ブラウザ アクション、ページ アクションのアクションに予約されています。これらのコマンドは、標準コマンドのように command.onCommand イベントをディスパッチしません。
ポップアップの開閉に基づいてアクションを実行する必要がある場合は、ポップアップの JavaScript 内で DOMContentLoaded イベントをリッスンすることを検討してください。
範囲
デフォルトでは、コマンドのスコープは Chrome ブラウザに限定されます。つまり、ブラウザにフォーカスが当たっていない場合、コマンド ショートカットは無効になります。Chrome 35 以降では、拡張機能のデベロッパーは必要に応じてコマンドを「グローバル」としてマークできます。グローバル コマンドは、Chrome がフォーカスされていない場合でも機能します。
グローバル コマンドのキーボード ショートカットの候補は Ctrl+Shift+[0..9] に制限されます。これは、他のアプリケーションでショートカットがオーバーライドされるリスクを最小限に抑えるための保護対策です。たとえば、Alt+P がグローバルとして許可されている場合、印刷ダイアログを開くキーボード ショートカットが他のアプリケーションで機能しない可能性があります。
エンドユーザーは、chrome://extensions/shortcuts で公開されている UI を使用して、グローバル コマンドを任意のキーの組み合わせに自由に再マッピングできます。
例:
manifest.json:
{
"name": "My extension",
...
"commands": {
"toggle-feature-foo": {
"suggested_key": {
"default": "Ctrl+Shift+5"
},
"description": "Toggle feature foo",
"global": true
}
},
...
}
例
次の例では、Commands API のコア機能を使用します。
基本コマンド
コマンドを使用すると、拡張機能でロジックをユーザーが呼び出せるキーボード ショートカットにマッピングできます。コマンドでは、次の例に示すように、拡張機能のマニフェストでのコマンド宣言とリスナーの登録のみが必要です。
manifest.json:
{
"name": "Command demo - basic",
"version": "1.0",
"manifest_version": 3,
"background": {
"service_worker": "service-worker.js"
},
"commands": {
"inject-script": {
"suggested_key": "Ctrl+Shift+Y",
"description": "Inject a script on the page"
}
}
}
service-worker.js:
chrome.commands.onCommand.addListener((command) => {
console.log(`Command "${command}" triggered`);
});
アクション コマンド
コンセプトと使用方法セクションで説明されているように、コマンドを拡張機能のアクションにマッピングすることもできます。次の例では、ユーザーが拡張機能のアクションをクリックするか、キーボード ショートカットをトリガーしたときに、現在のページにアラートを表示するコンテンツ スクリプトを挿入します。
manifest.json:
{
"name": "Commands demo - action invocation",
"version": "1.0",
"manifest_version": 3,
"background": {
"service_worker": "service-worker.js"
},
"permissions": ["activeTab", "scripting"],
"action": {},
"commands": {
"_execute_action": {
"suggested_key": {
"default": "Ctrl+U",
"mac": "Command+U"
}
}
}
}
service-worker.js:
chrome.action.onClicked.addListener((tab) => {
chrome.scripting.executeScript({
target: {tabId: tab.id},
func: contentScriptFunc,
args: ['action'],
});
});
function contentScriptFunc(name) {
alert(`"${name}" executed`);
}
// This callback WILL NOT be called for "_execute_action"
chrome.commands.onCommand.addListener((command) => {
console.log(`Command "${command}" called`);
});
登録されたコマンドを検証する
拡張機能が、別の拡張機能ですでに使用されているショートカットを登録しようとすると、2 番目の拡張機能のショートカットが想定どおりに登録されません。この可能性を予測し、インストール時に競合をチェックすることで、より堅牢なエンドユーザー エクスペリエンスを提供できます。
service-worker.js:
chrome.runtime.onInstalled.addListener((details) => {
if (details.reason === chrome.runtime.OnInstalledReason.INSTALL) {
checkCommandShortcuts();
}
});
// Only use this function during the initial install phase. After
// installation the user may have intentionally unassigned commands.
function checkCommandShortcuts() {
chrome.commands.getAll((commands) => {
let missingShortcuts = [];
for (let {name, shortcut} of commands) {
if (shortcut === '') {
missingShortcuts.push(name);
}
}
if (missingShortcuts.length > 0) {
// Update the extension UI to inform the user that one or more
// commands are currently unassigned.
}
});
}
型
Command
プロパティ
-
説明
文字列 省略可
拡張機能コマンドの説明
-
name
文字列 省略可
拡張機能コマンドの名前
-
ショートカット
文字列 省略可
このコマンドに対して有効なショートカット。有効でない場合は空白。
メソッド
getAll()
chrome.commands.getAll(
callback?: function,
)
この拡張機能に登録されているすべての拡張機能コマンドとそのショートカット（有効な場合）を返します。Chrome 110 より前は、このコマンドは _execute_action を返していませんでした。
戻り値
-
Promise<Command[]>
Chrome 96 以降Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために用意されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されるのと同じ型で解決されます。