Эта страница переведена с помощью 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 ( Option в macOS), Shift , MacCtrl (только в macOS), Command (только в macOS), Search (только в ChromeOS)

Примечание: Tab была удалена из списка поддерживаемых клавиш в Chrome 33 по соображениям доступности.

Ключевые требования к комбинации

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

Примечание: Использование комбинаций клавиш, включающих Ctrl+Alt запрещено во избежание конфликтов с клавишей AltGr .

Обработка событий команд

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
    }
  },
  ...
}

Примеры

Приведенные ниже примеры демонстрируют основные возможности 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`);
});

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

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

Примечание: _execute_action не будет отображаться в списке команд, возвращаемых функцией commands.getAll() .

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

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

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

Методы

getAll()

Обещать

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

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

Параметры

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

Возвраты

Promise< Command []>
Chrome 96+
Выполняется проверка с помощью списка зарегистрированных команд.
Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

События

onCommand

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

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

Параметры

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

chrome.команды Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Описание

Манифест

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

Поддерживаемые клавиши

Ключевые требования к комбинации

Обработка событий команд

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

Объем

Примеры

Базовая команда

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

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

Типы

Command

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

Методы

getAll()

Параметры

Возвраты

События

onCommand

Параметры

chrome.команды