向 Office 加载项添加自定义键盘快捷方式

项目
09/27/2024

键盘快捷方式（也称为组合键）使加载项的用户能够更高效地工作。键盘快捷方式还通过提供鼠标的替代项，改进了残障用户的加载项辅助功能。

向外接程序添加键盘快捷方式有三个步骤。

配置加载项的清单。
创建或编辑快捷方式 JSON 文件以定义操作及其键盘快捷方式。
使用 Office.actions.associate API 将自定义操作映射到其函数。

先决条件

键盘快捷方式目前仅在以下平台和 Excel 和 Word 版本中受支持。

Office 网页版
Windows 版 Office
- Excel：版本 2102 (内部版本 13801.20632) 及更高版本
- Word：版本 2408 (内部版本 17928.20114) 及更高版本
Mac 版 Office
- Excel：版本 16.55 (21111400) 及更高版本
- Word：版本 16.88 (24081116) 及更高版本

此外，键盘快捷方式仅适用于支持以下要求集的平台。有关要求集及其使用方式的信息，请参阅指定 Office 应用程序和 API 要求。

SharedRuntime 1.1
如果加载项为用户提供了用于自定义键盘快捷方式的选项，则 KeyboardShortcuts 1.1 ()

提示

若要从已配置键盘快捷方式的外接程序的工作版本开始，请克隆并运行 “对 Office 外接程序使用键盘快捷方式”操作示例。准备好将键盘快捷方式添加到自己的外接程序时，请继续阅读本文。

配置清单

需要对清单进行两个小更改。一个是允许加载项使用共享运行时，另一个是指向你在其中定义了键盘快捷方式的 JSON 格式的文件。

将加载项配置为使用共享运行时

添加自定义键盘快捷方式需要外接程序使用共享运行时。有关详细信息，请参阅配置外接程序以使用共享运行时。

将映射文件链接到清单

紧靠在 (不在清单中 VersionOverrides> 元素) < 内部，添加 ExtendedOverrides 元素。将 Url 属性设置为项目中 JSON 文件的完整 URL，稍后将创建此 URL。

    ...
    </VersionOverrides>  
    <ExtendedOverrides Url="https://contoso.com/addin/shortcuts.json"></ExtendedOverrides>
</OfficeApp>

创建或编辑快捷方式 JSON 文件

自定义键盘快捷方式在 JSON 文件中定义。此文件描述键盘快捷方式及其将调用的操作。 JSON 文件的完整架构位于 extended-manifest.schema.json。

在外接程序项目中，创建一个 JSON 文件。请确保文件的路径与为 UrlExtendedOverrides 元素的属性指定的位置匹配。
将以下标记添加到该文件中。请注意以下有关代码的信息。
- “actions”数组包含定义要调用的操作的对象。 “actions.id”和“actions.name”属性是必需的。
- “actions.id”属性唯一标识使用键盘快捷方式调用的操作。
- “actions.name”属性必须描述键盘快捷方式的操作。当多个加载项之间或与 Microsoft 365 发生快捷方式冲突时，你提供的说明将显示在向用户显示的对话框中。 Office 将加载项的名称追加在说明末尾的括号中。有关如何处理与键盘快捷方式冲突的详细信息，请参阅避免由其他加载项使用组合键。
- “type”属性是可选的。目前，仅支持“ExecuteFunction”类型。
- 指定的操作将映射到在后续步骤中创建的函数。在此示例中，稍后会将“ShowTaskpane”映射到调用方法的 Office.addin.showAsTaskpane 函数，将“HideTaskpane”映射到调用该方法的 Office.addin.hide 函数。
- “快捷方式”数组包含将键组合映射到操作的对象。需要“shortcuts.action”、“shortcuts.key”和“shortcuts.key.default”属性。
- “shortcuts.action”属性的值必须与适用操作对象的“actions.id”属性匹配。
- 可以自定义特定于平台的快捷方式。在此示例中，“shortcuts”对象为以下每个平台自定义快捷方式：“windows”、“mac”和“web”。必须为每个快捷方式定义默认快捷键。如果未为特定平台指定组合键，则会将其用作回退键。
提示

有关如何创建自定义组合键的指南，请参阅自定义组合键指南。
```
{
    "actions": [
        {
            "id": "ShowTaskpane",
            "type": "ExecuteFunction",
            "name": "Show task pane"
        },
        {
            "id": "HideTaskpane",
            "type": "ExecuteFunction",
            "name": "Hide task pane"
        }
    ],
    "shortcuts": [
        {
            "action": "ShowTaskpane",
            "key": {
                "default": "Ctrl+Alt+Up",
                "mac": "Command+Shift+Up",
                "web": "Ctrl+Alt+1",
                "windows": "Ctrl+Alt+Up"
            }
        },
        {
            "action": "HideTaskpane",
            "key": {
                "default": "Ctrl+Alt+Down",
                "mac": "Command+Shift+Down",
                "web": "Ctrl+Alt+2",
                "windows": "Ctrl+Alt+Up"
            }
        }
    ]
}
```

将自定义操作映射到其函数

在项目中，打开 FunctionFile> 元素中 HTML 页面加载的< JavaScript 文件。

在 JavaScript 文件中，使用 Office.actions.associate API 将 JSON 文件中指定的每个操作映射到 JavaScript 函数。将以下 JavaScript 添加到文件。请注意以下有关代码的信息。

第一个参数是 JSON 文件中的操作之一。
第二个参数是当用户按下映射到 JSON 文件中操作的组合键时运行的函数。

Office.actions.associate("ShowTaskpane", () => {
    return Office.addin.showAsTaskpane()
        .then(() => {
            return;
        })
        .catch((error) => {
            return error.code;
        });
});

Office.actions.associate("HideTaskpane", () => {
    return Office.addin.hide()
        .then(() => {
            return;
        })
        .catch((error) => {
            return error.code;
        });
});

自定义组合键指南

使用以下准则为加载项创建自定义组合键。

键盘快捷方式必须至少包含一个修饰键， (Alt/Option、Ctrl/Command、Shift) 和一个其他键。这些键必须使用字符联接 + 。
macOS 平台上支持命令修饰键。
在 macOS 上，Alt 键映射到 Option 键。在 Windows 上，命令键映射到 Ctrl 键。
Shift 键不能用作唯一的修饰键。它必须与 Alt/Option 或 Ctrl/Command 结合使用。
组合键可以包括字符“A-Z”、“a-z”、“0-9”以及标点符号“-”、“_”和“+”。按照约定，键盘快捷方式中不使用小写字母。
当两个字符链接到标准键盘上的同一物理键时，它们是自定义键盘快捷方式中的同义词。例如，Alt+a 和 Alt+A 是相同的快捷方式，Ctrl+- 和 Ctrl+_ (“-”和“_”链接到同一物理键) 。

注意

必须同时按下自定义键盘快捷方式。 Office 外接程序不支持 KeyTips，也称为顺序键快捷方式 (例如 Alt+H、H) 。

无法重写的浏览器快捷方式

在 Web 上使用自定义键盘快捷方式时，浏览器使用的一些键盘快捷方式无法被加载项覆盖。以下列表是正在进行的工作。如果发现其他无法重写的组合，请使用本页底部的反馈工具告知我们。

Ctrl+N
Ctrl+Shift+N
Ctrl+T
Ctrl+Shift+T
Ctrl+W
Ctrl+PgUp/PgDn

避免其他加载项使用组合键

Microsoft 365 已使用许多键盘快捷方式。避免为已在使用的加载项注册键盘快捷方式。但是，在某些情况下，可能需要替代现有的键盘快捷方式或处理已注册同一键盘快捷方式的多个加载项之间的冲突。

发生冲突时，用户首次尝试使用冲突键盘快捷方式时将看到一个对话框。请注意，此对话框中显示的加载项选项的文本来自快捷方式 JSON 文件中的“actions.name”属性。

对单个快捷方式使用两个不同操作的冲突模式。

用户可以选择键盘快捷方式将采取的操作。进行选择后，将保存首选项以供将来使用同一快捷方式。按用户、每个平台保存快捷方式首选项。如果用户希望更改其首选项，他们可以从“告诉我”搜索框中调用“重置 Office 加载项快捷方式首选项”命令。调用命令会清除用户的所有加载项快捷方式首选项，当用户下次尝试使用冲突快捷方式时，将再次提示用户显示冲突对话框。

Excel 中的“告诉我”搜索框，其中显示了“重置 Office 加载项快捷方式首选项”操作。

为了获得最佳用户体验，建议尽量减少键盘快捷方式与这些良好做法的冲突。

仅使用以下模式的键盘快捷方式： Ctrl+Shift+Alt+x，其中 x 是其他键。
避免在 Excel 和 Word 中使用已建立的键盘快捷方式。有关列表，请参阅以下内容：
- Excel 中的键盘快捷方式
- Word中的键盘快捷方式
当键盘焦点位于加载项 UI 中时， Ctrl+空格键 和 Ctrl+Shift+F10 将不起作用，因为这些是重要的辅助功能快捷方式。
在 Windows 或 Mac 计算机上，如果 “重置 Office 加载项快捷方式首选项” 命令在搜索菜单上不可用，则用户可以通过上下文菜单自定义功能区来手动将命令添加到功能区。

本地化键盘快捷方式的说明

在以下方案中，可能需要本地化自定义键盘快捷方式。

加载项支持多个区域设置。
加载项支持不同的字母、书写系统或键盘布局。

有关如何本地化键盘快捷方式 JSON 的信息，请参阅本地化扩展替代。

为特定用户启用快捷方式自定义

注意

本部分所述的 API 需要 KeyboardShortcuts 1.1 要求集。

外接程序的用户可将加载项的操作重新分配到备用键盘组合。

使用 Office.actions.replaceShortcuts 方法将用户的自定义键盘组合分配给加载项操作。方法采用类型的 {[actionId:string]: string|null}参数，其中 actionId是必须在外接程序的扩展清单 JSON 中定义的操作 ID 的子集。值是用户的首选组合键。该值也可以是 null，这将删除该actionId的任何自定义项，还原指定的默认键盘组合。

如果用户登录到 Microsoft 365，则自定义组合将保存在每个平台的用户漫游设置中。匿名用户当前不支持自定义快捷方式。

const userCustomShortcuts = {
    ShowTaskpane: "Ctrl+Shift+1",
    HideTaskpane: "Ctrl+Shift+2"
};

Office.actions.replaceShortcuts(userCustomShortcuts)
    .then(() => {
        console.log("Successfully registered shortcut.");
    })
    .catch((error) => {
        if (error.code == "InvalidOperation") {
            console.log("ActionId doesn't 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((inUseArray) => {
        const availableShortcuts = inUseArray.filter((shortcut) => {
            return !shortcut.inUse;
        });
        console.log(availableShortcuts);
        const usedShortcuts = inUseArray.filter((shortcut) => {
            return shortcut.inUse;
        });
        console.log(usedShortcuts);
    });

跨受支持的 Microsoft 365 应用实现自定义键盘快捷方式

你可以实现自定义键盘快捷方式，以便跨受支持的 Microsoft 365 应用（如 Excel 和 Word）使用。如果用于在每个应用上执行相同任务的实现不同，则必须使用 Office.actions.associate 方法为每个应用调用不同的回调函数。以下代码是一个示例。

const host = Office.context.host;
if (host === Office.HostType.Excel) {
    Office.actions.associate("ChangeFormat", changeFormatExcel);
} else if (host === Office.HostType.Word) {
    Office.actions.associate("ChangeFormat", changeFormatWord);
}
...

通过