chrome.commands

说明

使用 Commands API 添加可在扩展程序中触发操作的键盘快捷键，例如用于打开浏览器操作或向扩展程序发送命令的操作。

清单

必须在清单中声明以下键才能使用此 API。

"commands"

概念和用法

借助 Commands API，扩展程序开发者可以定义特定命令，并将其绑定到默认的按键组合。扩展程序接受的每个命令都必须在扩展程序清单中声明为 "commands" 对象的属性。

属性键将用作命令的名称。命令对象可以采用两个属性。

suggested_key

一个可选属性，用于声明命令的默认快捷键。如果省略，则命令将解除绑定。此属性可以采用字符串或对象值。

  • 字符串值 - 用于指定应在所有平台上使用的默认键盘快捷键。

  • 借助对象值，扩展程序开发者可以为每个平台自定义快捷键。提供平台专用快捷方式时，有效的对象属性为 default、chromeos、linux、mac 和 windows。

如需了解更多详情，请参阅按键组合要求。

description

用于向用户提供有关命令用途的简短说明的字符串。此字符串会显示在扩展程序键盘快捷键管理界面中。标准命令需要提供说明，但操作命令会忽略说明。

一个扩展程序可以包含多个命令，但最多只能指定四个建议的键盘快捷键。用户可以通过 chrome://extensions/shortcuts 对话框手动添加更多快捷方式。

支持的按键

以下键可用作命令快捷键。键定义区分大小写。如果尝试加载键大小写有误的扩展程序，则会在安装时导致清单解析错误。

Alpha 键
A … Z
数字键
0 … 9
标准键字符串

常规 - Comma、Period、Home、End、PageUp、PageDown、Space、Insert、Delete

箭头键 - Up、Down、Left、Right

媒体按键 - MediaNextTrack、MediaPlayPause、MediaPrevTrack、MediaStop

辅助键字符串

Ctrl、Alt、Shift、MacCtrl（仅限 macOS）、Command（仅限 macOS）、Search（仅限 ChromeOS）

按键组合要求

  • 扩展程序命令快捷键必须包含 Ctrl 或 Alt。

    • 修饰符不能与媒体按键结合使用。

    • 在许多 macOS 键盘上，Alt 是指 Option 键。

    • 在 macOS 上，Command 或 MacCtrl 也可以代替 Ctrl 或 Alt（请参阅下一个要点）。

  • 在 macOS 上，Ctrl 会自动转换为 Command。

    • Command 还可在 "mac" 快捷键中使用，以明确引用 Command 键。

    • 如需在 macOS 上使用 Control 键，请在定义 "mac" 快捷键时将 Ctrl 替换为 MacCtrl。

    • 在其他平台的组合中使用 MacCtrl 会导致验证错误，并阻止安装扩展程序。

  • Shift 是所有平台上的可选修饰符。

  • Search 是 ChromeOS 专有的可选修饰符。

  • 某些操作系统和 Chrome 快捷键（例如窗口管理）始终优先于扩展程序命令快捷键，并且无法替换。

处理命令事件

manifest.json:

{
  "name": "My extension",
  ...
  "commands": {
    "run-foo": {
      "suggested_key": {
        "default": "Ctrl+Shift+Y",
        "mac": "Command+Shift+Y"
      },
      "description": "Run \"foo\" on the current page."
    },
    "_execute_action": {
      "suggested_key": {
        "windows": "Ctrl+Shift+Y",
        "mac": "Command+Shift+Y",
        "chromeos": "Ctrl+Shift+U",
        "linux": "Ctrl+Shift+J"
      }
    }
  },
  ...
}

在您的服务工作器中，您可以使用 onCommand.addListener 将处理程序绑定到清单中定义的每个命令。例如：

service-worker.js：

chrome.commands.onCommand.addListener((command) => {
  console.log(`Command: ${command}`);
});

操作命令

_execute_action（Manifest V3）、_execute_browser_action（Manifest V2）和 _execute_page_action（Manifest V2）命令分别用于触发操作、浏览器操作或网页操作。这些命令不会像标准命令那样分派 command.onCommand 事件。

如果您需要根据弹出式窗口打开情况执行操作，不妨考虑在弹出式窗口的 JavaScript 中监听 DOMContentLoaded 事件。

范围

默认情况下，命令的范围仅限于 Chrome 浏览器。这意味着，当浏览器没有焦点时，命令快捷键将处于非活动状态。从 Chrome 35 开始，扩展程序开发者可以选择将某个命令标记为“全局”。即使 Chrome 未获得焦点，全局命令也能正常运行。

全局命令的键盘快捷键建议仅限于 Ctrl+Shift+[0..9]。这是一种保护措施，旨在最大限度地降低在其他应用中替换快捷键的风险。例如，如果允许将 Alt+P 设为全局快捷键，则用于打开打印对话框的键盘快捷键可能无法在其他应用中使用。

最终用户可以使用 chrome://extensions/shortcuts 中公开的界面，将全局命令自由重新映射到首选的按键组合。

示例：

manifest.json:

{
  "name": "My extension",
  ...
  "commands": {
    "toggle-feature-foo": {
      "suggested_key": {
        "default": "Ctrl+Shift+5"
      },
      "description": "Toggle feature foo",
      "global": true
    }
  },
  ...
}

示例

以下示例展示了 Commands API 的核心功能。

基本命令

借助命令，扩展程序可以将逻辑映射到可由用户调用的键盘快捷键。在最基本的层面上，命令只需要在扩展程序的清单中声明命令，并进行监听器注册，如以下示例所示。

manifest.json:

{
  "name": "Command demo - basic",
  "version": "1.0",
  "manifest_version": 3,
  "background": {
    "service_worker": "service-worker.js"
  },
  "commands": {
    "inject-script": {
      "suggested_key": "Ctrl+Shift+Y",
      "description": "Inject a script on the page"
    }
  }
}

service-worker.js：

chrome.commands.onCommand.addListener((command) => {
  console.log(`Command "${command}" triggered`);
});

操作命令

如概念和用法部分中所述，您还可以将命令映射到扩展程序的操作。以下示例会注入一个内容脚本，当用户点击扩展程序的操作或触发快捷键时，该脚本会在当前页面上显示一条提醒。

manifest.json:

{
  "name": "Commands demo - action invocation",
  "version": "1.0",
  "manifest_version": 3,
  "background": {
    "service_worker": "service-worker.js"
  },
  "permissions": ["activeTab", "scripting"],
  "action": {},
  "commands": {
    "_execute_action": {
      "suggested_key": {
        "default": "Ctrl+U",
        "mac": "Command+U"
      }
    }
  }
}

service-worker.js：

chrome.action.onClicked.addListener((tab) => {
  chrome.scripting.executeScript({
    target: {tabId: tab.id},
    func: contentScriptFunc,
    args: ['action'],
  });
});

function contentScriptFunc(name) {
  alert(`"${name}" executed`);
}

// This callback WILL NOT be called for "_execute_action"
chrome.commands.onCommand.addListener((command) => {
  console.log(`Command "${command}" called`);
});

验证已注册的命令

如果某个扩展程序尝试注册已被其他扩展程序使用的快捷键，则第二个扩展程序的快捷键将无法按预期注册。您可以预料到这种可能性，并在安装时检查是否存在冲突，从而提供更稳定可靠的最终用户体验。

service-worker.js：

chrome.runtime.onInstalled.addListener((details) => {
  if (details.reason === chrome.runtime.OnInstalledReason.INSTALL) {
    checkCommandShortcuts();
  }
});

// Only use this function during the initial install phase. After
// installation the user may have intentionally unassigned commands.
function checkCommandShortcuts() {
  chrome.commands.getAll((commands) => {
    let missingShortcuts = [];

    for (let {name, shortcut} of commands) {
      if (shortcut === '') {
        missingShortcuts.push(name);
      }
    }

    if (missingShortcuts.length > 0) {
      // Update the extension UI to inform the user that one or more
      // commands are currently unassigned.
    }
  });
}

类型

Command

属性

  • 说明

    字符串（选填）

    扩展程序命令说明

  • name

    字符串（选填）

    扩展程序命令的名称

  • 快捷方式

    字符串（选填）

    此命令的有效快捷键，如果无效，则为空。

方法

getAll()

prometido 
chrome.commands.getAll(
  callback?: function,
)

返回此扩展程序的所有已注册扩展程序命令及其快捷方式（如果处于活动状态）。在 Chrome 110 之前，此命令不会返回 _execute_action。

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    (commands: Command[]) => void

返回

  • Promise<Command[]>

    Chrome 96 及更高版本

    清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

事件

onCommand

chrome.commands.onCommand.addListener(
  callback: function,
)

当使用键盘快捷键激活已注册的命令时触发。

参数

  • callback

    函数

    callback 参数如下所示： 

    (command: string, tab?: tabs.Tab) => void