This page was saved using WebZIP 7.0.3.1030 offline browser on 12/24/13 11:31:36.
Address: https://crxdoc-zh.appspot.com/extensions/commands.html
Title: chrome.commands - Google Chrome 扩展程序开发文档（非官方中文版）  •  Size: 27556

chrome.commands

描述： 使用命令 API 添加快捷键，触发您的扩展程序中的操作，例如打开浏览器按钮或向扩展程序发送命令。
可用版本： 从 Chrome 25 开始稳定支持。
清单文件： "commands": {...}

清单文件

您必须将将 manifest_version（清单文件版本）设置为（至少）2 才能使用该 API。

用法

命令 API 允许您定义特定的命令，并为它们绑定默认的组合键。您的扩展程序接受的每一个命令都必须在清单文件中列出，作为 'commands' 键的属性。扩展程序可以包含很多命令，但是只能指定四个推荐的按键。用户可以在 chrome://extensions 页面手动添加更多的快捷键。

支持的按键包括：A～Z、0～9、逗号、句号、Home、End、PageUp、PageDown、Insert、Delete、方向键（上、下、左、右）和多媒体键（上一曲（MediaPrevTrack）、下一曲（MediaNextTrack）、播放/暂停（MediaPlayPause）、停止（MediaStop））。

注意：所有组合键必须包含 Ctrl* 或 Alt 中的一个，不允许使用涉及到 Ctrl+Alt 的组合键，以免与 AltGr 键冲突。除了 Alt 或 Ctrl 外还可以使用 Shift 键，但不是必须使用。组合键（例如 Ctrl）不能与多媒体按键一起使用。出于辅助功能的原因，从 Chrome 33 开始不支持 Tab 键。

* 另外请注意，在 Mac 中 Ctrl 会自动转换为 Command 键。如果您希望使用 Ctrl，请指定“MacCtrl”。

某些 Chrome 浏览器的快捷键（例如窗口管理）优先级始终比扩展程序命令的快捷键高，不能被覆盖。 

{
  "name": "我的扩展程序",
  ...
  "commands": {
    "toggle-feature-foo": {
      "suggested_key": {
        "default": "Ctrl+Shift+Y",
        "mac": "Command+Shift+Y"
      },
      "description": "切换 foo 特性"
    },
    "_execute_browser_action": {
      "suggested_key": {
        "windows": "Ctrl+Shift+Y",
        "mac": "Command+Shift+Y",
        "chromeos": "Ctrl+Shift+U",
        "linux": "Ctrl+Shift+J"
      }
    },
    "_execute_page_action": {
      "suggested_key": {
        "default": "Ctrl+E",
        "windows": "Alt+P",
        "mac": "Option+P"
      }
    }
  },
  ...
}

在您的后台网页中，您可以通过 onCommand.addListener 为清单文件中定义的每一个命令（除了 '_execute_browser_action' 与 '_execute_page_action'）绑定处理函数。例如： 

chrome.commands.onCommand.addListener(function(command) {
  console.log('Command:', command);
});

'_execute_browser_action'（执行浏览器按钮）与 '_execute_page_action'（执行页面按钮）命令为打开您的扩展程序的弹出内容而保留，它们通常不会产生您可以处理的事件。如果您需要在弹出内容打开时进行处理，考虑在弹出内容的代码中监听 'onDomReady' 事件。

chrome.commands 参考

类型

Command

Command 的属性

name ( optional string )

扩展程序命令的名称。

description ( optional string )

扩展程序命令的描述。

shortcut ( optional string )

当前用于该命令的快捷键，或者如果不活动的话则为空。

方法

getAll

chrome.commands.getAll(function callback)

返回当前扩展程序注册的所有扩展程序命令以及它们的快捷键（如果处于活动状态的话）。

参数

callback ( optional function )

调用时返回注册的命令。

如果您指定了 callback 参数，它应该指定一个如下形式的函数： 

function(array of Command commands) {...};

commands ( array of Command )

事件

onCommand

当注册的命令通过快捷键激活时产生。

addListener

chrome.commands.onCommand.addListener(function callback)

参数

callback ( function )

callback 参数应该指定一个如下形式的函数： 

function(string command) {...};

command ( string )