chrome.commands

refresh date: 2026-09-25 robots: noindex

Описание

Используйте commands API, чтобы добавить быстрые клавиши, которые запускают действия в расширении, например открывают действие браузера или отправляют команду расширению.

Манифест

Чтобы использовать этот API, в манифесте нужно объявить следующие ключи:

"commands"

Использование

Commands API позволяет разработчикам расширений определять команды и связывать их с сочетаниями клавиш по умолчанию. Каждая команда, которую принимает расширение, должна быть объявлена как свойство объекта "commands" в манифесте расширения.

Ключ свойства используется в качестве названия команды. Объекты команд могут иметь два свойства.

suggested_key

Необязательное свойство, которое объявляет сочетания клавиш по умолчанию для команды. Если его не указать, команда не будет привязана. Это свойство может принимать значение строки или объекта.

  • Строковое значение определяет сочетание клавиш по умолчанию, которое будет использоваться на всех платформах.

  • Значение объекта позволяет разработчику расширения настраивать сочетание клавиш для каждой платформы. При указании быстрых клавиш для конкретной платформы допустимыми свойствами объекта являются default, chromeos, linux, mac и windows.

Подробнее о требованиях к комбинациям клавиш…

description

Строка, которая используется для предоставления пользователю краткого описания назначения команды. Эта строка появляется в интерфейсе управления быстрыми клавишами расширения. Описания обязательны для стандартных команд, но игнорируются для команд действий.

У расширения может быть много команд, но для него можно указать не более четырех сочетаний клавиш. Пользователь может вручную добавить больше ярлыков в диалоговом окне 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 (Option в macOS), Shift, MacCtrl (только в macOS), Command (только в macOS), Search (только в ChromeOS)

Требования к сочетаниям клавиш

  • В сочетаниях клавиш для команд расширений должна использоваться клавиша Ctrl или Alt.

    • Модификаторы нельзя использовать в сочетании с мультимедийными клавишами.

  • В macOS Ctrl автоматически преобразуется в Command.

    • Чтобы использовать клавишу Control в macOS, замените Ctrl на MacCtrl при определении сочетания клавиш "mac".

    • Если вы используете 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, как стандартные команды.

Если вам нужно выполнить действие на основе открытия всплывающего окна, рассмотрите возможность прослушивания события DOMContentLoaded внутри JavaScript всплывающего окна.

Область действия

По умолчанию команды применяются к браузеру Chrome. Это означает, что, когда фокус не установлен на браузере, сочетания клавиш не работают. Начиная с версии Chrome 35 разработчики расширений могут помечать команды как глобальные. Глобальные команды работают, даже если окно Chrome неактивно.

Предлагаемые сочетания клавиш для глобальных команд ограничены Ctrl+Shift+[0..9]. Это защитная мера, которая позволяет снизить риск переопределения сочетаний клавиш в других приложениях. Например, если бы сочетание Alt+P было разрешено в качестве глобального, то сочетание клавиш для открытия диалогового окна печати могло бы не работать в других приложениях.

Конечные пользователи могут переназначить глобальные команды на предпочитаемые сочетания клавиш в интерфейсе по адресу 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`);
});

Проверьте зарегистрированные команды

Если расширение пытается зарегистрировать сочетание клавиш, которое уже используется другим расширением, то сочетание клавиш второго расширения не будет зарегистрировано. Вы можете обеспечить более удобное использование для конечного пользователя, предвидя такую возможность и проверяя наличие конфликтов при установке.

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

Свойства

  • описание

    Строка (необязательно)

    Описание команды расширения

  • name

    Строка (необязательно)

    Название команды расширения.

  • ярлык

    Строка (необязательно)

    Активное сочетание клавиш для этой команды или пустое поле, если оно неактивно.

Методы

getAll()

Promise 
chrome.commands.getAll(
  callback?: function,
): Promise<Command[]>

Возвращает все зарегистрированные команды расширения и их сочетания клавиш (если они активны). В версиях до Chrome 110 эта команда не возвращала _execute_action.

Параметры

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    (commands: Command[]) => void

Возвраты

  • Promise<Command[]>

    Chrome 96 и более поздних версий;

    Возвращает список зарегистрированных команд.

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

События

onCommand

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

Срабатывает, когда зарегистрированная команда активируется с помощью сочетания клавиш.

Параметры

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

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

    • команда

      string

    • табуляция

      tabs.Tab необязательно