chrome.commands

描述 使用命令 API 添加快捷键,以便触发应用中的操作,例如打开浏览器按钮或向应用发送命令。
可用版本 从 Chrome 25 开始支持。
清单文件 "commands": {...}

清单文件

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

用法

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

支持的按键包括: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 键。

某些百度浏览器的快捷键(例如窗口管理)优先级始终比应用命令的快捷键高,不能被覆盖。

      {
        "name": "我的应用",
        ...
        "commands": {
          "toggle-feature-foo": {
            "suggested_key": {
              "default": "Ctrl+Shift+Y",
              
        
            },
            "description": "切换 foo 特性"
          },
          "_execute_browser_action": {
            "suggested_key": {
              "windows": "Ctrl+Shift+Y",
              
        
            }
          },
          "_execute_page_action": {
            "suggested_key": {
              "default": "Ctrl+Shift+E",
              "windows": "Alt+Shift+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 35 开始,在桌面版百度浏览器上,命令的范围可以是全局的,即使百度浏览器没有焦点时仍然可以使用。

用户可以在 chrome://extensions > 快捷键用户界面中使用任意快捷键作为全局快捷键,但是应用开发者在全局快捷键中只能指定 Ctrl+Shift+[0..9]。这样是为了尽可能避免与其他应用程序中的快捷键重复,例如,如果允许将 Alt+P 作为全局快捷键,其他应用程序中的打印快捷键就不能正常使用。

例如:

      {
        "name": "我的应用",
        ...
        "commands": {
          "toggle-feature-foo": {
            "suggested_key": {
              "default": "Ctrl+Shift+5"
            },
            "description": "开启/关闭某项功能",
            "global": true
          }
        },
        ...
      }

摘要

类型
Command
方法
getAll chrome.commands.getAll(function callback)
事件
onCommand

类型

Command

属性
string (可选)
name

应用命令的名称。

string (可选)
description

应用命令的描述。

string (可选)
shortcut

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

方法

getAll

chrome.commands.getAll(function callback)

返回当前应用注册的所有应用命令以及它们的快捷键(如果处于活动状态的话)。

参数
function (可选)
callback

调用时返回注册的命令。

如果您指定了 callback 参数,它应该是一个如下形式的函数:

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

事件

onCommand

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

addListener

chrome.commands.onCommand.addListener(function callback)
参数
function callback

callback 参数应该是一个如下形式的函数:

function(string command) {...};
string command