chrome.commands

説明

Command API を使用すると、拡張機能での操作(ブラウザの操作を開く操作や拡張機能にコマンドを送信する操作など)をトリガーするキーボード ショートカットを追加できます。

マニフェスト

この API を使用するには、次のキーをマニフェストで宣言する必要があります。

"commands"

コンセプトと使用方法

拡張機能のデベロッパーは Commands API を使用して特定のコマンドを定義し、それらをデフォルトにバインドできる できます。拡張機能が受け入れる各コマンドは、 拡張機能のマニフェスト内の "commands" オブジェクト。

プロパティキーがコマンド名として使用されます。コマンド オブジェクトには 2 つのプロパティがあります。

suggested_key

コマンドのデフォルトのキーボード ショートカットを宣言するオプションのプロパティ。省略すると、 コマンドがバインド解除されます。このプロパティには文字列またはオブジェクト値を指定できます。

  • 文字列値は、すべてのアプリケーションで使用されるデフォルトのキーボード ショートカットを指定します。 説明します。

  • オブジェクト値により、拡張機能のデベロッパーは各オブジェクトのキーボード ショートカットをカスタマイズできます。 説明します。プラットフォーム固有のショートカットを指定する場合、有効なオブジェクト プロパティは default です。 chromeoslinuxmacwindows

詳細については、キーの組み合わせの要件をご覧ください。

description

ユーザーにコマンドの簡単な説明を提供するために使用される文字列。この文字列 拡張機能キーボード ショートカットの管理 UI に表示されます。標準の アクション コマンドでは無視されます。

拡張機能には多数のコマンドを使用できますが、推奨されるキーボード ショートカットは 4 つまで指定できます。「 ユーザーが chrome://extensions/shortcuts ダイアログから手動でショートカットを追加できる

サポートされているキー

次のキーは、使用可能なコマンド ショートカットです。鍵の定義では大文字と小文字が区別されます。試行 大文字と小文字の使い方が正しくないキーで拡張機能を読み込むと、 インストール時間が短縮されます

英字キー
A ... Z
数字キー
0 ... 9
標準のキー文字列

全般 - CommaPeriodHomeEndPageUpPageDownSpaceInsertDelete

矢印キー - UpDownLeftRight

メディアキー – MediaNextTrackMediaPlayPauseMediaPrevTrackMediaStop

修飾キーの文字列

CtrlAlt(macOS では Option)、ShiftMacCtrl(macOS のみ)、Command(macOS のみ)、Search(ChromeOS のみ)

で確認できます。

キーの組み合わせの要件

  • 拡張機能コマンドのショートカットには、Ctrl または Alt のいずれかを含める必要があります。

    • 修飾子はメディアキーと組み合わせて使用することはできません
  • macOS では、Ctrl は自動的に Command に変換されます。

    • macOS で Control キーを使用するには、"mac" を定義するときに CtrlMacCtrl に置き換えます。 できます。

    • 別のプラットフォームの組み合わせで 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 イベントを発生させます。

ポップアップが開くことに基づいて対応が必要な場合は、 DOMContentLoaded イベントを実装する必要があります。

範囲

デフォルトでは、コマンドのスコープは Chrome ブラウザです。つまりブラウザが コマンド ショートカットは無効です。Chrome 35 以降、拡張機能のデベロッパーは 必要に応じて、コマンドを「global」とマークします。Chrome にフォーカスがないときも、グローバル コマンドを使用できます。

グローバル コマンドでのキーボード ショートカットの候補は Ctrl+Shift+[0..9] に制限されています。これは 他のアプリケーションでショートカットがオーバーライドされるリスクを たとえば、Alt+P はグローバル(印刷ダイアログを開くためのキーボード ショートカット)として許可されていました。 他のアプリケーションでは動作しない場合があります。

エンドユーザーは、公開されている UI を使用して、グローバル コマンドを好みのキーの組み合わせに自由に再マッピングできます。 chrome://extensions/shortcuts です。

例:

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

プロパティ

  • description

    文字列(省略可)

    拡張コマンドの説明

  • name

    文字列(省略可)

    拡張機能コマンドの名前

  • ショートカット

    文字列(省略可)

    このコマンドで有効なショートカットです。有効になっていない場合は空白になります。

メソッド

getAll()

<ph type="x-smartling-placeholder"></ph> 約束
chrome.commands.getAll(
  callback?: function,
)

この拡張機能に登録されているすべての拡張機能コマンドとそのショートカット(有効な場合)を返します。Chrome 110 より前では、このコマンドは _execute_action を返しませんでした。

パラメータ

  • callback

    関数(省略可)

    callback パラメータは次のようになります。

    (commands: Command[]) => void

戻り値

  • Promise<コマンド[]>

    Chrome 96 以降

    Promise は Manifest V3 以降でサポートされていますが、 下位互換性が確保されます同じ関数呼び出しで両方を使用することはできません。「 Promise はコールバックに渡された型と同じ型で解決されます。

イベント

onCommand

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

登録済みのコマンドがキーボード ショートカットを使用して有効化されたときに呼び出されます。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。

    (command: string, tab?: tabs.Tab) => void

    • command

      文字列

    • タブ

      tabs.Tab オプション