説明
コマンド 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
(macOS の場合はOption
)、Shift
、MacCtrl
(macOS のみ)、Command
(macOS のみ)、Search
(ChromeOS のみ)
キーの組み合わせの要件
拡張機能のコマンド ショートカットには、
Ctrl
またはAlt
を含める必要があります。- 修飾子をメディアキーと併用することはできません。
macOS では、
Ctrl
は自動的に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"
}
}
},
...
}
Service Worker では、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((reason) => {
if (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
プロパティ
-
description
string(省略可)
拡張機能コマンドの説明
-
name
string(省略可)
拡張機能コマンドの名前
-
ショートカット
string(省略可)
このコマンドに対して有効なショートカット。アクティブでない場合は空白になります。
Methods
getAll()
chrome.commands.getAll(
callback?: function,
)
この拡張機能とそのショートカット(有効な場合)に登録されているすべての拡張機能コマンドを返します。Chrome 110 より前では、このコマンドは _execute_action
を返しませんでした。
戻り値
-
Promise<Command[]>
Chrome 96 以降Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。