向 Office 加载项添加自定义键盘快捷方式
键盘快捷方式(也称为组合键)使加载项的用户能够更高效地工作。 键盘快捷方式还通过提供鼠标的替代项,改进了残障用户的加载项辅助功能。
重要
键盘快捷方式目前仅在 Excel 上受支持,并且仅在以下平台和版本上受支持:
- Excel 网页版
- Windows 上的 Excel:版本 2102 (内部版本 13801.20632) 及更高版本
- Mac 上的 Excel:版本 16.48 及更高版本
注意
键盘快捷方式仅适用于支持以下要求集的平台。 有关要求集及其使用方式的详细信息,请参阅 指定 Office 应用程序和 API 要求。
- SharedRuntime 1.1
- 如果加载项允许用户自定义键盘快捷方式,则还需要: KeyboardShortcuts 1.1
注意
若要从已启用键盘快捷方式的加载项的工作版本开始,请克隆并运行示例 Excel 键盘快捷方式。 准备好将键盘快捷方式添加到自己的外接程序时,请继续阅读本文。
向外接程序添加键盘快捷方式有三个步骤。
- 配置加载项的清单。
- 创建或编辑快捷方式 JSON 文件 以定义操作及其键盘快捷方式。
- 添加 Office.actions.associate API 的一个或多个运行时调用,以将函数映射到每个操作。
配置清单
需要对清单进行两个小更改。 一个是允许加载项使用共享运行时,另一个是指向你在其中定义了键盘快捷方式的 JSON 格式的文件。
将加载项配置为使用共享运行时
添加自定义键盘快捷方式需要外接程序使用 共享运行时。 有关详细信息,请参阅 配置外接程序以使用共享运行时。
将映射文件链接到清单
紧靠在 (不在清单中 VersionOverrides> 元素) < 内部,添加 ExtendedOverrides 元素。 将 Url
属性设置为项目中 JSON 文件的完整 URL,稍后将创建此 URL。
...
</VersionOverrides>
<ExtendedOverrides Url="https://contoso.com/addin/shortcuts.json"></ExtendedOverrides>
</OfficeApp>
创建或编辑快捷方式 JSON 文件
在项目中创建 JSON 文件。 请确保文件的路径与为 Url
ExtendedOverrides 元素的 属性指定的位置匹配。 此文件将描述键盘快捷方式以及它们将调用的操作。
在 JSON 文件中,有两个数组。 actions 数组将包含定义要调用的操作的对象,快捷方式数组将包含将组合键映射到操作的对象。 以下是示例。
{ "actions": [ { "id": "SHOWTASKPANE", "type": "ExecuteFunction", "name": "Show task pane for add-in" }, { "id": "HIDETASKPANE", "type": "ExecuteFunction", "name": "Hide task pane for add-in" } ], "shortcuts": [ { "action": "SHOWTASKPANE", "key": { "default": "Ctrl+Alt+Up" } }, { "action": "HIDETASKPANE", "key": { "default": "Ctrl+Alt+Down" } } ] }
有关 JSON 对象的详细信息,请参阅 构造操作对象 和 构造快捷方式对象。 快捷方式 JSON 的完整架构位于 extended-manifest.schema.json。
注意
本文中可以使用“CONTROL”代替“Ctrl”。
操作将映射到你创建的函数。 在此示例中,你将将“SHOWTASKPANE”映射到调用 Office.addin.showAsTaskpane 方法的函数,并将“HIDETASKPANE”映射到调用 Office.addin.hide 方法的函数。
创建操作到其函数的映射
在项目中,打开 FunctionFile> 元素中 HTML 页面加载的< JavaScript 文件。
在 JavaScript 文件中,使用 Office.actions.associate API 将 JSON 文件中指定的每个操作映射到 JavaScript 函数。 将以下 JavaScript 添加到 文件。 请注意以下有关代码的信息。
- 第一个参数是 JSON 文件中的操作之一。
- 第二个参数是在用户按下映射到 JSON 文件中操作的组合键时运行的函数。
Office.actions.associate("SHOWTASKPANE", showTaskPane); Office.actions.associate("HIDETASKPANE", hideTaskPane); function showTaskPane() { return Office.addin.showAsTaskpane() .then(() => { console.log("Task pane is visible."); }) .catch((error) => { console.log(error.code); }); } function hideTaskPane() { return Office.addin.hide() .then(() => { console.log("Task pane is hidden."); }) .catch((error) => { console.log(error.code); }) }
按照前面的步骤,加载项可以通过按 Ctrl+Alt+向上键和 Ctrl+Alt+向下键来切换任务窗格的可见性。 GitHub 中 Office 外接程序示例存储库中的 Excel 键盘快捷方式 示例也显示了相同的行为。
详细信息和限制
构造操作对象
指定shortcuts.json数组中的 actions
对象时,请遵循以下准则。
- 属性名称和
id
name
是必需的。 - 属性
id
用于唯一标识使用键盘快捷方式调用的操作。 - 属性
name
必须是描述操作的用户友好字符串。 它必须是字符 A - Z、a - z、0 - 9 以及标点符号“-”、“_”和“+”的组合。 - 属性是可选的。 目前仅
ExecuteFunction
支持类型。
示例如下。
"actions": [
{
"id": "SHOWTASKPANE",
"type": "ExecuteFunction",
"name": "Show task pane for add-in"
},
{
"id": "HIDETASKPANE",
"type": "ExecuteFunction",
"name": "Hide task pane for add-in"
}
]
快捷方式 JSON 的完整架构位于 extended-manifest.schema.json。
构造快捷方式对象
指定shortcuts.json数组中的 shortcuts
对象时,请遵循以下准则。
- 属性名称
action
、key
和default
是必需的。 - 属性的值
action
是一个字符串,并且必须与操作对象中的一个id
属性相匹配。 - 属性
default
可以是字符 A - Z、-z、0 - 9 以及标点符号“-”、“_”和“+”的任意组合。 (按约定,这些属性中不使用小写字母。) - 属性
default
必须包含至少一个修饰键的名称, (Alt、Ctrl、Shift) ,并且仅包含一个其他键。 - Shift 不能用作唯一的修饰键。 将 Shift 与 Alt 或 Ctrl 结合使用。
- 对于 Mac,我们还支持命令修饰键。
- 对于 Mac,Alt 映射到 Option 键。 对于 Windows,命令映射到 Ctrl 键。
- 当两个字符链接到标准键盘中的同一物理键时,它们就是 属性中的
default
同义词;例如,Alt+a 和 Alt+A 是同一个快捷方式,Ctrl+- 和 Ctrl+_ 也是如此,因为“-”和“_”是相同的物理键。 - “+”字符表示同时按下两侧的键。
示例如下。
"shortcuts": [
{
"action": "SHOWTASKPANE",
"key": {
"default": "Ctrl+Alt+Up"
}
},
{
"action": "HIDETASKPANE",
"key": {
"default": "Ctrl+Alt+Down"
}
}
]
快捷方式 JSON 的完整架构位于 extended-manifest.schema.json。
注意
Office 外接程序不支持键提示(也称为顺序键快捷方式),例如用于选择填充颜色 Alt+H、H 的 Excel 快捷方式。
避免其他加载项使用组合键
Office 已使用许多键盘快捷方式。 避免为已在使用的加载项注册键盘快捷方式。 但是,在某些情况下,可能需要替代现有的键盘快捷方式或处理已注册同一键盘快捷方式的多个加载项之间的冲突。
发生冲突时,用户首次尝试使用冲突键盘快捷方式时将看到一个对话框。 请注意,此对话框中显示的外接程序选项的文本来自 name
文件中操作对象中的 shortcuts.json
属性。
用户可以选择键盘快捷方式将采取的操作。 进行选择后,将保存首选项以供将来使用同一快捷方式。 按用户、每个平台保存快捷方式首选项。 如果用户希望更改其首选项,他们可以从“告诉我”搜索框中调用“重置 Office 加载项快捷方式首选项”命令。 调用命令会清除用户的所有加载项快捷方式首选项,当用户下次尝试使用冲突快捷方式时,将再次提示用户显示冲突对话框。
为了获得最佳用户体验,建议通过这些良好做法尽量减少与 Excel 的冲突。
- 仅使用以下模式的键盘快捷方式: Ctrl+Shift+Alt+x,其中 x 是其他键。
- 如果需要更多键盘快捷方式,请检查 Excel 键盘快捷方式列表,并避免在加载项中使用其中任何快捷方式。
- 当键盘焦点位于加载项 UI 中时, Ctrl+空格键 和 Ctrl+Shift+F10 将不起作用,因为这些是重要的辅助功能快捷方式。
- 在 Windows 或 Mac 计算机上,如果“重置 Office 加载项快捷方式首选项”命令在搜索菜单上不可用,则用户可以通过上下文菜单自定义功能区来手动将命令添加到功能区。
自定义每个平台的键盘快捷方式
可以自定义特定于平台的快捷方式。 下面是为以下每个平台自定义快捷方式的 对象的一个示例 shortcuts
: windows
、 mac
、 web
。 请注意,对于每个快捷方式,仍必须有一个 default
快捷键。
在以下示例中, default
键是任何未指定平台的回退键。 唯一未指定的平台是 Windows,因此密钥 default
将仅适用于 Windows。
"shortcuts": [
{
"action": "SHOWTASKPANE",
"key": {
"default": "Ctrl+Alt+Up",
"mac": "Command+Shift+Up",
"web": "Ctrl+Alt+1",
}
},
{
"action": "HIDETASKPANE",
"key": {
"default": "Ctrl+Alt+Down",
"mac": "Command+Shift+Down",
"web": "Ctrl+Alt+2"
}
}
]
本地化键盘快捷方式 JSON
如果外接程序支持多个区域设置,则需要本地化 name
操作对象的 属性。 此外,如果外接程序支持的任何区域设置具有不同的字母或书写系统,因此键盘也不同,则你可能需要本地化快捷方式。 有关如何本地化键盘快捷方式 JSON 的信息,请参阅 本地化扩展替代。
无法重写的浏览器快捷方式
在 Web 上使用自定义键盘快捷方式时,加载项无法重写浏览器使用的某些键盘快捷方式。此列表是正在进行的工作。 如果发现其他无法重写的组合,请使用本页底部的反馈工具告知我们。
- Ctrl+N
- Ctrl+Shift+N
- Ctrl+T
- Ctrl+Shift+T
- Ctrl+W
- Ctrl+PgUp/PgDn
为特定用户启用自定义键盘快捷方式
加载项可让用户将加载项的操作重新分配到备用键盘组合。
注意
本部分所述的 API 需要 KeyboardShortcuts 1.1 要求集。
使用 Office.actions.replaceShortcuts 方法将用户的自定义键盘组合分配给加载项操作。 方法采用 类型的 {[actionId:string]: string|null}
参数,其中 actionId
是必须在外接程序的扩展清单 JSON 中定义的操作 ID 的子集。 值是用户的首选组合键。 该值也可以是 null
,这将删除任何自定义项, actionId
并还原为外接程序的扩展清单 JSON 中定义的默认键盘组合。
如果用户登录到 Office,则自定义组合将保存在每个平台的用户漫游设置中。 匿名用户当前不支持自定义快捷方式。
const userCustomShortcuts = {
SHOWTASKPANE:"CTRL+SHIFT+1",
HIDETASKPANE:"CTRL+SHIFT+2"
};
Office.actions.replaceShortcuts(userCustomShortcuts)
.then(function () {
console.log("Successfully registered.");
})
.catch(function (ex) {
if (ex.code == "InvalidOperation") {
console.log("ActionId does not exist or shortcut combination is invalid.");
}
});
若要了解用户已使用的快捷方式,请调用 Office.actions.getShortcuts 方法。 此方法返回类型的 [actionId:string]:string|null}
对象,其中的值表示用户调用指定操作时必须使用的当前键盘组合。 这些值可能来自三个不同的源:
- 如果与快捷方式发生冲突,并且用户已选择 (该键盘组合的本机或其他加载项) 使用不同的操作,则返回的值将为
null
,因为快捷方式已被重写,并且用户当前没有可用于调用该外接程序操作的键盘组合。 - 如果已使用 Office.actions.replaceShortcuts 方法自定义快捷方式,则返回的值将是自定义键盘组合。
- 如果快捷方式尚未重写或自定义,它将从加载项的扩展清单 JSON 返回值。
示例如下。
Office.actions.getShortcuts()
.then(function (userShortcuts) {
for (const action in userShortcuts) {
let shortcut = userShortcuts[action];
console.log(action + ": " + shortcut);
}
});
如 避免其他加载项使用组合键中所述,最好避免快捷方式冲突。 若要发现是否已使用一个或多个组合键,请将它们作为字符串数组传递给 Office.actions.areShortcutsInUse 方法。 方法返回一个报表,其中包含已以 类型的 {shortcut: string, inUse: boolean}
对象数组的形式使用的键组合。 属性 shortcut
是组合键,例如“CTRL+SHIFT+1”。 如果组合已注册到另一个操作,则 inUse
属性设置为 true
。 例如,[{shortcut: "CTRL+SHIFT+1", inUse: true}, {shortcut: "CTRL+SHIFT+2", inUse: false}]
。 以下代码片段是一个示例:
const shortcuts = ["CTRL+SHIFT+1", "CTRL+SHIFT+2"];
Office.actions.areShortcutsInUse(shortcuts)
.then(function (inUseArray) {
const availableShortcuts = inUseArray.filter(function (shortcut) { return !shortcut.inUse; });
console.log(availableShortcuts);
const usedShortcuts = inUseArray.filter(function (shortcut) { return shortcut.inUse; });
console.log(usedShortcuts);
});
后续步骤
- 请参阅 Excel 键盘快捷方式 示例加载项。
- 在使用清单的扩展替代中获取 有关使用扩展替代的概述。