说明
使用 Commands API 添加键盘快捷键，以触发扩展程序中的操作，例如打开浏览器操作或向扩展程序发送命令的操作。
清单
概念和用法
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`);
});
操作命令
如概念和使用部分中所述，您还可以将命令映射到扩展程序的 action。以下示例注入了一个内容脚本，当用户点击扩展程序的操作或触发键盘快捷键时，该脚本会在当前页面上显示一个提醒。
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.
}
});
}