commands

Czytasz angielską wersję tego artykułu, ponieważ nie ma jeszcze tłumaczenia dla tego języka. Pomóż nam przetłumaczyć ten artykuł!

Type Object
Mandatory No
Example
"commands": {
  "toggle-feature": {
    "suggested_key": {
      "default": "Ctrl+Shift+Y",
      "linux": "Ctrl+Shift+U"
    },
    "description": "Send a 'toggle-feature' event"
  }
}

Use the commands key to define one or more keyboard shortcuts for your extension.

Each keyboard shortcut is defined with a name, a combination of keys, and a description. Once you've defined commands in your extension's manifest.json, you can listen for their associated key combinations with the commands JavaScript API.

Syntax

The commands key is an object, and each shortcut is a property of it. The property's name is the name of the shortcut.

Each shortcut's value is an object, with up to 2 properties:

  1. suggested_key: the combination of keys that activate the shortcut.
  2. description: a string that describes the shortcut; i.e. what it does.

The suggested_key property is an object with any of the following properties (all strings):

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

The value of each property is the keyboard shortcut for the command on that platform, as a string containing keys separated by "+". The value for "default" is used on all platforms that are not explicitly listed.

For example:

"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"
    }
  }
}

This JSON defines 2 shortcuts:

  1. "toggle-feature", accessed with Ctrl+Shift+U on Linux, and Alt+Shift+U on all other platforms.
  2. "do-another-thing", accessed with Ctrl+Shift+Y on all platforms.

You could then listen for the "toggle-feature" command with code like this:

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

Special shortcuts

There are 3 special shortcuts with default actions, for which the commands.onCommand event is not fired:

  • _execute_browser_action: works like a click on the extension's browser action.
  • _execute_page_action: works like a click on the extension's page action.
  • _execute_sidebar_action: opens the extension's sidebar. Only supported in Firefox 54 and newer.

For example, this JSON defines a key combination that clicks the extension's browser action:

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

Shortcut values

There are two valid formats for shortcut keys: as a key combination or as a media key.

Key combinations

On Macs, "Ctrl" is interpreted as "Command", so if you actually need "Ctrl", specify "MacCtrl".

Key combinations must consist of 2 or 3 keys:

  1. modifier (mandatory, except for function keys). This can be any of: "Ctrl", "Alt", "Command", or "MacCtrl".
  2. secondary modifier (optional). If supplied, this must be either "Shift" or (for Firefox ≥ 63) any one of "Ctrl", "Alt", "Command", or "MacCtrl". Must not be the modifier already used as the main modifier.
  3. key (mandatory). This can be any one of:
    • the letters AZ
    • the numbers 09
    • the function keys F1F12
    • Comma, Period, Home, End, PageUp, PageDown, Space, Insert, Delete, Up, Down, Left, Right

The key is then given as a string containing the set of key values, in the order listed above, separated by "+". For example, "Ctrl+Shift+Z".

If a key combination is already used by the browser (like "Ctrl+P") or by an existing add-on, then you can't override it. You can define it, but your event handler will not be called when the user presses the key combination.

Media keys

Alternatively, the shortcut may be specified as one of the following media keys:

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

Updating shortcuts

Shortcuts can be updated via commands.update(). Users can also update shortcuts via the "Manage Extension Shortcuts" option at about:addons in Firefox, as shown in this video. In Chrome, users can change shortcuts at chrome://extensions/shortcuts.

Example

Define a single keyboard shortcut, using only the default key combination:

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

Define two keyboard shortcuts, one with a platform-specific key combination:

"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"
    }
  }
}

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxOperaFirefox for Android
commandsChrome Full support YesEdge No support NoFirefox Full support 48Opera Full support YesFirefox Android No support No
F1-F12Chrome Full support YesEdge No support NoFirefox Full support 53Opera Full support YesFirefox Android No support No
MediaNextTrackChrome Full support YesEdge No support NoFirefox Full support 57
Notes
Full support 57
Notes
Notes macOS support requires the global command feature which isn't supported yet. See Bug 1251795.
Notes Can only register one Media* command at a time. See Bug 1251795.
Opera Full support YesFirefox Android No support No
MediaPlayPauseChrome Full support YesEdge No support NoFirefox Full support 57
Notes
Full support 57
Notes
Notes macOS support requires the global command feature which isn't supported yet. See Bug 1251795.
Notes Can only register one Media* command at a time. See Bug 1251795.
Opera Full support YesFirefox Android No support No
MediaPrevTrackChrome Full support YesEdge No support NoFirefox Full support 57
Notes
Full support 57
Notes
Notes macOS support requires the global command feature which isn't supported yet. See Bug 1251795.
Notes Can only register one Media* command at a time. See Bug 1251795.
Opera Full support YesFirefox Android No support No
MediaStopChrome Full support YesEdge No support NoFirefox Full support 57
Notes
Full support 57
Notes
Notes macOS support requires the global command feature which isn't supported yet. See Bug 1251795.
Notes Can only register one Media* command at a time. See Bug 1251795.
Opera Full support YesFirefox Android No support No
Secondary modifier other than ShiftChrome No support NoEdge No support NoFirefox Full support 63Opera No support NoFirefox Android No support No
globalChrome Full support YesEdge No support NoFirefox No support NoOpera Full support YesFirefox Android No support No
_execute_sidebar_actionChrome No support NoEdge No support NoFirefox Full support 54Opera No support NoFirefox Android No support No

Legend

Full support  
Full support
No support  
No support
See implementation notes.
See implementation notes.