Команды

Ключ commands представляет собой объект, а каждое сочетание клавиш является его свойством. Имя свойства — это имя сочетания клавиш.

Значение каждого сочетания клавиш — это объект с двумя свойствами:

1. suggested_key: сочетание клавиш, активирующее сочетание.
2. description: строка, описывающая сочетание клавиш; то есть, что оно делает.

Свойство suggested_key — это объект с любыми из следующих свойств (все строки):

• "default"
• "mac"
• "linux"
• "windows"
• "chromeos"
• "android"
• "ios"

Значение каждого свойства — это сочетание клавиш для команды на данной платформе, представленное строкой, содержащей клавиши, разделенные "+". Значение для "default" используется на всех платформах, которые не указаны явно.

Например:

"commands": {
  "toggle-feature": {
    "suggested_key": {
      "default": "Alt+Shift+U",
      "linux": "Ctrl+Shift+U"
    },
    "description": "Send a 'toggle-feature' event to the extension"
  },
  "do-another-thing": {
    "suggested_key": {
      "default": "Ctrl+Shift+Y"
    }
  }
}

Этот JSON определяет 2 сочетания клавиш:

1. "toggle-feature", доступное с помощью Ctrl + Shift + U в Linux и Alt + Shift + U на всех остальных платформах.
2. "do-another-thing", доступное с помощью Ctrl + Shift + Y на всех платформах.

Затем вы можете прослушивать команду "toggle-feature" с помощью такого кода:

browser.commands.onCommand.addListener((command) => {
  if (command === "toggle-feature") {
    console.log("Toggling the feature!");
  }
});

Существует 4 специальных сочетания клавиш с действиями по умолчанию, для которых событие commands.onCommand не срабатывает:

• _execute_browser_action: работает как щелчок по кнопке панели инструментов панели инструментов, созданной с помощью browserAction или указанной в ключе browser_action в манифесте manifest.json.
• _execute_action: работает как щелчок по кнопке панели инструментов панели инструментов, созданной с помощью action или указанной в ключе action в манифесте manifest.json.
• _execute_page_action: работает как щелчок по кнопке адресной строки адресной строки, созданной с помощью pageAction или указанной в ключе page_action в манифесте manifest.json.
• _execute_sidebar_action: открывает боковую панель расширения, указанную в ключе sidebar_action манифеста manifest.json.

Доступность этих специальных сочетаний клавиш варьируется в зависимости от версии манифеста и браузера, как показано ниже:

Например, этот JSON определяет сочетание клавиш, которое щелкает по кнопке расширения в браузере:

"commands": {
  "_execute_browser_action": {
    "suggested_key": {
      "default": "Ctrl+Shift+Y"
    }
  }
}

Существуют два допустимых формата для сочетаний клавиш: как сочетание клавиш или как медиа-клавиша.

Сочетания клавиш должны состоять из 2 или 3 клавиш:

1. модификатор (обязательно, за исключением функциональных клавиш). Может быть любым из: "Ctrl", "Alt", "Command", или "MacCtrl".
2. вторичный модификатор (необязательно). Если указан, он должен быть либо "Shift", либо (для Firefox ≥ 63) любым из "Ctrl", "Alt", "Command", или "MacCtrl". Не должен совпадать с уже используемым основным модификатором.
3. клавиша (обязательно). Может быть любой из:
   • букв A – Z
   • цифр 0 – 9
   • функциональных клавиш F1 – F12
   • Comma, Period, Home, End, PageUp, PageDown, Space, Insert, Delete, Up, Down, Left, Right

Затем клавиша указывается как строка, содержащая значения клавиш в указанном порядке, разделенные "+". Например, "Ctrl+Shift+Z".

Если сочетание клавиш уже используется браузером (например, "Ctrl+P") или существующим дополнением, то его нельзя переопределять. Вы можете его определить, но обработчик событий не будет вызван при нажатии пользователем этого сочетания.

В качестве альтернативы сочетание клавиш может быть указано как одна из следующих медиа-клавиш:

• "MediaNextTrack"
• "MediaPlayPause"
• "MediaPrevTrack"
• "MediaStop"

Сочетания клавиш можно обновить с помощью commands.update(). Пользователи также могут обновлять сочетания клавиш в опции «Управление сочетаниями клавиш расширения» в about:addons в Firefox, как показано на этом видео. В Chrome пользователи могут изменить сочетания клавиш в chrome://extensions/shortcuts.

Определите одно сочетание клавиш, используя только стандартное сочетание:

"commands": {
  "toggle-feature": {
    "suggested_key": {
      "default": "Ctrl+Shift+Y"
    },
    "description": "Send a 'toggle-feature' event"
  }
}

Определите два сочетания клавиш, одно с сочетанием клавиш, специфичным для платформы:

"commands": {
  "toggle-feature": {
    "suggested_key": {
      "default": "Alt+Shift+U",
      "linux": "Ctrl+Shift+U"
    },
    "description": "Send a 'toggle-feature' event"
  },
  "do-another-thing": {
    "suggested_key": {
      "default": "Ctrl+Shift+Y"
    }
  }
}