chrome.commands

説明

マニフェスト

コンセプトと使用方法

拡張機能のデベロッパーは、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((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.
    }
  });
}

chrome.commands.getAll(
  callback?: function,
)

chrome.commands.onCommand.addListener(
  callback: function,
)