说明
您可以使用 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 事件。
如果您需要根据弹出式窗口的打开情况采取措施,不妨考虑监听弹出式窗口的 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()
chrome.commands.getAll(
callback?: function,
)
返回此扩展程序及其快捷方式(如果处于活动状态)的所有已注册扩展程序命令。在 Chrome 110 之前,此命令不返回 _execute_action
。