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

项目
08/18/2023

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

重要

键盘快捷方式目前仅在 Excel 上受支持，并且仅在以下平台和版本上受支持：

Excel 网页版
Windows 上的 Excel：版本 2102 (内部版本 13801.20632) 及更高版本
Mac 上的 Excel：版本 16.48 及更高版本

注意

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

SharedRuntime 1.1
如果加载项允许用户自定义键盘快捷方式，则还需要： KeyboardShortcuts 1.1

注意

若要从已启用键盘快捷方式的加载项的工作版本开始，请克隆并运行示例 Excel 键盘快捷方式。准备好将键盘快捷方式添加到自己的外接程序时，请继续阅读本文。

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

配置加载项的清单。
Create或编辑快捷方式 JSON 文件以定义操作及其键盘快捷方式。
添加 Office.actions.associate API 的一个或多个运行时调用，以将函数映射到每个操作。

配置清单

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

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

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

将映射文件链接到清单

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

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

Create或编辑快捷方式 JSON 文件

Create项目中的 JSON 文件。请确保文件的路径与为 UrlExtendedOverrides 元素的属性指定的位置匹配。此文件将描述键盘快捷方式以及它们将调用的操作。

在 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 函数。

Create操作到其函数的映射

在项目中，打开 FunctionFile> 元素中 HTML 页面加载的< JavaScript 文件。
在 JavaScript 文件中，使用 Office.actions.associate API 将 JSON 文件中指定的每个操作映射到 JavaScript 函数。将以下 JavaScript 添加到文件。请注意以下有关代码的信息。
- 第一个参数是 JSON 文件中的操作之一。
- 第二个参数是在用户按下映射到 JSON 文件中操作的组合键时运行的函数。
```
Office.actions.associate('-- action ID goes here--', function () {

});
```
若要继续示例，请使用 'SHOWTASKPANE' 作为第一个参数。

对于函数的正文，请使用 Office.addin.showAsTaskpane 方法打开外接程序的任务窗格。完成后，代码应如下所示：

Office.actions.associate('SHOWTASKPANE', function () {
    return Office.addin.showAsTaskpane()
        .then(function () {
            return;
        })
        .catch(function (error) {
            return error.code;
        });
});

添加第二个函数调用 Office.actions.associate ，将 HIDETASKPANE 操作映射到调用 Office.addin.hide 的函数。示例如下。

Office.actions.associate('HIDETASKPANE', function () {
    return Office.addin.hide()
        .then(function () {
            return;
        })
        .catch(function (error) {
            return error.code;
        });
});

按照前面的步骤，加载项可以通过按 Ctrl+Alt+向上键和 Ctrl+Alt+向下键来切换任务窗格的可见性。 GitHub 中 Office 外接程序示例存储库中的 Excel 键盘快捷方式示例也显示了相同的行为。

详细信息和限制

构造操作对象

指定shortcuts.json数组中的 actions 对象时，请遵循以下准则。

属性名称和 idname 是必需的。
属性 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 中的“告诉我”搜索框，其中显示了“重置 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 键盘快捷方式示例加载项。
在使用清单的扩展替代中获取有关使用扩展替代的概述。

Share via

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

配置清单

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

将映射文件链接到清单

Create或编辑快捷方式 JSON 文件

Create操作到其函数的映射

详细信息和限制

构造操作对象

构造快捷方式对象

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

自定义每个平台的键盘快捷方式

本地化键盘快捷方式 JSON

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

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

后续步骤

反馈

其他资源