Эта страница переведена с помощью Cloud Translation API.

chrome.команды

Описание

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

Манифест

Для использования этого API в манифесте необходимо объявить следующие ключи.

"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 , Shift , MacCtrl (только macOS), Command (только macOS), Search (только ChromeOS)

Требования к комбинации клавиш

Ярлыки команд расширения должны включать Ctrl или Alt .
- Модификаторы нельзя использовать в сочетании с медиа-ключами.
- На многих клавиатурах macOS Alt относится к клавише Option.
- В macOS вместо Ctrl или Alt также можно использовать Command или MacCtrl (см. следующий пункт).
В macOS Ctrl автоматически преобразуется в Command .
- Command также можно использовать в ярлыке "mac" для явной ссылки на клавишу Command.
- Чтобы использовать клавишу Control в macOS, замените Ctrl на MacCtrl при определении ярлыка "mac" .
- Использование MacCtrl в комбинации для другой платформы приведет к ошибке проверки и предотвратит установку расширения.
Shift — необязательный модификатор на всех платформах.
Search — это дополнительный модификатор, эксклюзивный для ChromeOS.
Определенные ярлыки операционной системы и Chrome (например, управление окнами) всегда имеют приоритет над ярлыками команд расширения и не могут быть переопределены.

Примечание. Комбинации клавиш, включающие Ctrl+Alt не допускаются во избежание конфликтов с клавишей AltGr .

Обрабатывать события команд

манифест.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 . Например:

сервис-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 .

Пример:

манифест.json:

{
  "name": "My extension",
  ...
  "commands": {
    "toggle-feature-foo": {
      "suggested_key": {
        "default": "Ctrl+Shift+5"
      },
      "description": "Toggle feature foo",
      "global": true
    }
  },
  ...
}

Примеры

Следующие примеры расширяют основные функции API команд.

Основная команда

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

манифест.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"
    }
  }
}

сервис-worker.js:

chrome.commands.onCommand.addListener((command) => {
  console.log(`Command "${command}" triggered`);
});

Команда действия

Как описано в разделе «Основы и использование» , вы также можете сопоставить команду с действием расширения. В следующем примере внедряется сценарий содержимого, который отображает предупреждение на текущей странице, когда пользователь либо щелкает действие расширения, либо запускает сочетание клавиш.

манифест.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"
      }
    }
  }
}

сервис-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`);
});

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

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

сервис-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

Характеристики

описание
строка необязательна
Описание команды расширения
имя
строка необязательна
Имя команды расширения
ярлык
строка необязательна
Ярлык активен для этой команды или пуст, если не активен.

Методы

getAll()

Обещать

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

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

Параметры

перезвонить
функция необязательна
Параметр callback выглядит так:
```
(commands: Command[]) => void
```
- команды
  Команда []

Возврат

Обещание< Команда []>
Хром 96+
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

События

onCommand

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

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

Параметры

перезвонить
функция
Параметр callback выглядит так:
```
(command: string, tab?: tabs.Tab) => void
```
- команда
  нить
- вкладка
  tabs.Tab необязательно