chrome/common/extensions/docs/templates/intros/commands.html

   1 <h2 id="manifest">Manifest</h2>
   2 <p>
   3 You must have a <code>"manifest_version"</code> of at least <code>2</code> to use this API.
   4 </p>
   5
   6 {{?is_apps +partials.warning_dev /}}
   7
   8 <h2 id="usage">Usage</h2>
   9 <p>The commands API allows you to define specific commands, and bind them to a
  10 default key combination. Each command your extension accepts must be listed in
  11 the manifest as an attribute of the 'commands' manifest key. An extension can
  12 have many commands but only 4 suggested keys can be specified. The user can
  13 manually add more shortcuts from the chrome://extensions/configureCommands
  14 dialog.</p>
  15
  16 <p>Supported keys: A-Z, 0-9, Comma, Period, Home, End, PageUp, PageDown, Insert,
  17 Delete, Arrow keys (Up, Down, Left, Right) and the Media Keys
  18 (MediaNextTrack, MediaPlayPause, MediaPrevTrack, MediaStop).</p>
  19
  20 <p>Note: All key combinations must include either Ctrl* or Alt. Combinations
  21 that involve Ctrl+Alt are not permitted in order to avoid conflicts with the
  22 AltGr key. Shift can be used in addition to Alt or Ctrl, but is not required.
  23 Modifiers (such as Ctrl) can not be used in combination with the Media Keys.
  24 Tab key was removed from list of supported keys in Chrome version 33 and above
  25 for accessibility reasons.<p>
  26
  27 <p>* Also note that on Mac 'Ctrl' is automatically converted to 'Command'. If
  28 you want 'Ctrl' instead, please specify 'MacCtrl'.</p>
  29
  30 <p>Certain Chrome shortcuts (e.g. window management) always take priority over
  31 Extension Command shortcuts and can not be overwritten.</p>
  32
  33 <pre data-filename="manifest.json">
  34 {
  35   "name": "My extension",
  36   ...
  37 <b>  "commands": {
  38     "toggle-feature-foo": {
  39       "suggested_key": {
  40         "default": "Ctrl+Shift+Y",
  41         "mac": "Command+Shift+Y"
  42       },
  43       "description": "Toggle feature foo"
  44     },
  45     "_execute_browser_action": {
  46       "suggested_key": {
  47         "windows": "Ctrl+Shift+Y",
  48         "mac": "Command+Shift+Y",
  49         "chromeos": "Ctrl+Shift+U",
  50         "linux": "Ctrl+Shift+J"
  51       }
  52     },
  53     "_execute_page_action": {
  54       "suggested_key": {
  55         "default": "Ctrl+Shift+E",
  56         "windows": "Alt+Shift+P",
  57         "mac": "Alt+Shift+P"
  58       }
  59     }
  60   }</b>,
  61   ...
  62 }</pre>
  63
  64 <p>In your background page, you can bind a handler to each of the commands
  65 defined in the manifest (except for '_execute_browser_action' and
  66 '_execute_page_action') via onCommand.addListener. For example:</p>
  67
  68 <pre>
  69 chrome.commands.onCommand.addListener(function(command) {
  70   console.log('Command:', command);
  71 });
  72 </pre>
  73
  74 <p>The '_execute_browser_action' and '_execute_page_action' commands are
  75 reserved for the action of opening your extension's popups. They won't normally
  76 generate events that you can handle. If you need to take action based on your
  77 popup opening, consider listening for an 'onDomReady' event inside your popup's
  78 code.
  79 </p>
  80
  81 <h2 id="usage">Scope</h2>
  82 <p>By default, Commands are scoped to the Chrome browser, which means that while
  83 the browser does not have focus, the shortcut will be inactive. On desktop
  84 Chrome, Commands can instead have global scope, as of version 35, and will then
  85 also work while Chrome does *not* have focus. NOTE: The exception here is
  86 ChromeOS, where global commands are not allowed at the moment.</p>
  87
  88 <p>The user is free to designate any shortcut as global using the UI in
  89 chrome://extensions \ Keyboard Shortcuts, but the extension developer is limited
  90 to specifying only Ctrl+Shift+[0..9] as global shortcuts. This is to minimize
  91 the risk of overriding shortcuts in other applications since if, for example,
  92 Alt+P were to be allowed as global, the printing shortcut might not work in
  93 other applications.</p>
  94
  95 <p>Example:</p>
  96
  97 <pre data-filename="manifest.json">
  98 {
  99   "name": "My extension",
 100   ...
 101   "commands": {
 102     "toggle-feature-foo": {
 103       "suggested_key": {
 104         "default": "Ctrl+Shift+5"
 105       },
 106       "description": "Toggle feature foo",
 107       <b>"global": true</b>
 108     }
 109   },
 110   ...
 111 }</pre>