chrome.команды

Описание

Манифест

Концепции и использование

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 (например, управление окнами) всегда имеют приоритет над сочетаниями клавиш команд расширения и не могут быть переопределены.

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

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`);
});

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

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

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(): Promise<Command[]>

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