说明
您可以使用 Command 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（macOS 上为Option）、Shift、MacCtrl（仅限 macOS）、Command（仅限 macOS）、Search（仅限 ChromeOS） 。
键组合要求
扩展程序命令快捷方式必须包含
Ctrl或Alt。- 修饰符不能与媒体键结合使用。
在 macOS 上，
Ctrl会自动转换为Command。如需在 macOS 上使用 Ctrl 键，请在定义
"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"
}
}
},
...
}
在 Service Worker 中，您可以将处理程序绑定到清单中定义的每个命令
使用 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 事件类似。
如果您需要根据弹出式窗口的打开情况采取相应措施，请考虑监听 DOMContentLoaded 事件。
范围
默认情况下，命令的作用域仅限于 Chrome 浏览器。这意味着，当浏览器 处于聚焦状态，命令快捷键无效。从 Chrome 35 开始，扩展程序开发者可以 （可选）将命令标记为“global”。当 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()
chrome.commands.getAll(
callback?: function,
)
返回此扩展程序及其快捷方式（如果处于活动状态）的所有已注册扩展程序命令。在 Chrome 110 之前，此命令不返回 _execute_action。