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

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

• Ярлыки команд расширения должны включать Ctrl или Alt .

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

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

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

  • Использование MacCtrl в комбинации для другой платформы приведет к ошибке проверки и предотвратит установку расширения.

• Shift — необязательный модификатор на всех платформах.

• Search — это дополнительный модификатор, эксклюзивный для ChromeOS.

• Некоторые ярлыки операционной системы и Chrome (например, управление окнами) всегда имеют приоритет над ярлыками команд расширения и не могут быть перезаписаны.

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

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

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

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