键盘快捷键

项目
02/13/2024

键盘快捷键是键盘快捷方式，通过为用户提供直观的方式来在 Mac Catalyst 和 Windows 上改进 .NET Multi-platform App UI (.NET MAUI) 应用的可用性和可访问性，无需直接导航应用 UI 即可调用常见操作或命令。

键盘快捷键由两个组件组成：

修饰符，包括 Shift、Ctrl 和 Alt。
键，包括字母数字键和特殊键。

在 .NET MAUI 中，键盘快捷键与菜单中公开的命令相关联，应使用菜单项指定。具体而言，.NET MAUI 键盘快捷键可以附加到 Mac Catalyst 和 Windows 菜单栏中的菜单项，以及 Windows 上下文菜单中的菜单项。有关菜单栏的详细信息，请参阅在 .NET MAUI 桌面应用中显示菜单栏。有关上下文菜单的详细信息，请参阅在 .NET MAUI 桌面应用中显示上下文菜单。

以下屏幕截图显示了包含键盘快捷键的菜单栏项和上下文菜单项：

Screenshot of menu bar items that include keyboard accelerators.

键盘快捷键由 KeyboardAccelerator 类表示，该类表示 MenuFlyoutItem 的快捷键。 KeyboardAccelerator 类定义以下属性：

Modifiers，类型为 KeyboardAcceleratorModifiers，表示键盘快捷方式的修饰符值，如 Ctrl 或 Shift。
Key，类型为 string?，表示键盘快捷方式的键值。

这些属性由 BindableProperty 对象提供支持；也就是说，它们可以作为数据绑定的目标。

KeyboardAcceleratorModifiers 枚举定义以下成员，这些成员用作 Modifiers 属性的值：

None，表示无修饰符。
Shift，指示 Mac Catalyst 和 Windows 上的 Shift 修饰符。
Ctrl，指示 Mac Catalyst 和 Windows 上的 Control 修饰符。
Alt，指示 Mac Catalyst 上的 Option 修饰符和 Windows 上的 Menu 修饰符。
Cmd，指示 Mac Catalyst 上的 Command 修饰符。
Windows，指示 Windows 上的 Windows 修饰符。

重要

键盘快捷键可以附加到 Mac Catalyst 和 Windows 上 MenuBarItem 中的 MenuFlyoutItem 对象，以及 Windows 上的 MenuFlyout 中。

下表概述了 .NET MAUI 支持的键盘快捷键格式：

平台	单键	多键
Mac Catalyst	没有修饰符、包含单个键的键盘快捷键。例如，使用 F1 键调用与菜单项关联的操作。	具有一个或多个修饰符、包含单个键的键盘快捷键。例如，使用 CMD+SHIFT+S 或 CMD+S 调用与菜单项关联的操作。
Windows	带有和不使用修饰符、包含单个键的键盘快捷键。例如，使用 F1 键调用与菜单项关联的操作。	具有一个或多个修饰符、包含单个键的键盘快捷键。例如，使用 CTRL+SHIFT+F 或 CTRL+F 调用与菜单项关联的操作。

创建键盘快捷键

通过将 KeyboardAccelerator 添加到 KeyboardAccelerators 集合，可以将前者附加到 MenuFlyoutItem 中：

<MenuFlyoutItem Text="Cut"
                Clicked="OnCutMenuFlyoutItemClicked">
    <MenuFlyoutItem.KeyboardAccelerators>
        <KeyboardAccelerator Modifiers="Ctrl"
                             Key="X" />
    </MenuFlyoutItem.KeyboardAccelerators>
</MenuFlyoutItem>

还可以在代码中指定键盘快捷键：

cutMenuFlyoutItem.KeyboardAccelerators.Add(new KeyboardAccelerator
{
    Modifiers = KeyboardAcceleratorModifiers.Ctrl,
    Key = "X"
});

按下键盘快捷键修饰符和键时，将调用与 MenuFlyoutItem 关联的操作。

重要

虽然可以将多个 KeyboardAccelerator 对象添加到 MenuFlyoutItem.KeyboardAccelerators 集合中，但只有集合中的第一个 KeyboardAccelerator 对象会在 MenuFlyoutItem 上显示其快捷方式。此外，在 Mac Catalyst 上，只有集合中第一个 KeyboardAccelerator 元素的键盘快捷方式才会导致调用与 MenuFlyoutItem 关联的操作。但是，在 Windows 上，MenuFlyoutItem.KeyboardAccelerators 集合中所有 KeyboardAccelerator 对象的键盘快捷方式都将导致调用 MenuFlyoutItem 操作。

指定多个修饰符

可以在两个平台上的 KeyboardAccelerator 指定多个修饰符：

<MenuFlyoutItem Text="Refresh"
                Command="{Binding RefreshCommand}">
    <MenuFlyoutItem.KeyboardAccelerators>
        <KeyboardAccelerator Modifiers="Shift,Ctrl"
                             Key="R" />
    </MenuFlyoutItem.KeyboardAccelerators>
</MenuFlyoutItem>

等效 C# 代码如下：

refreshMenuFlyoutItem.KeyboardAccelerators.Add(new KeyboardAccelerator
{
    Modifiers = KeyboardAcceleratorModifiers.Shift | KeyboardAcceleratorModifiers.Ctrl,
    Key = "R"
});

为每个平台指定键盘快捷键

通过 OnPlatform 标记扩展，可以在 XAML 中为每个平台指定不同的键盘快捷键修饰符和键：

<MenuFlyoutItem Text="Change Theme"
                Command="{Binding ChangeThemeCommand}">
    <MenuFlyoutItem.KeyboardAccelerators>
        <KeyboardAccelerator Modifiers="{OnPlatform MacCatalyst=Cmd, WinUI=Windows}"
                             Key="{OnPlatform MacCatalyst=T, WinUI=C}" />
    </MenuFlyoutItem.KeyboardAccelerators>
</MenuFlyoutItem>

等效 C# 代码如下：

KeyboardAcceleratorModifiers modifier = KeyboardAcceleratorModifiers.None;
string key = string.Empty;

if (DeviceInfo.Current.Platform == DevicePlatform.MacCatalyst)
{
    modifier = KeyboardAcceleratorModifiers.Cmd;
    key = "T";
}
else if (DeviceInfo.Current.Platform == DevicePlatform.WinUI)
{
    modifier = KeyboardAcceleratorModifiers.Windows;
    key = "C";
}

myMenuFlyoutItem.KeyboardAccelerators.Add(new KeyboardAccelerator
{
    Modifiers = modifier,
    Key = key
});

在键盘快捷键中使用特殊键

在 Windows 上，可以通过字符串常数或整数指定特殊键。有关常数和整数的列表，请参阅 VirtualKey 中的表。

注意

在 Windows 上，支持单键快捷键（所有字母数字和标点键、Delete、F2、空格键、Esc、多媒体键）和多键快捷键 (Ctrl+Shift+M)。但是，不支持 Gamepad 虚拟键。

在 Mac Catalyst 上，可以通过字符串常数指定特殊键。有关表示与特殊键对应的文本输入字符串的常数列表，请参阅 developer.apple.com 上的特殊键的输入字符串。

以下 XAML 演示了使用特殊键定义键盘快捷键的示例：

<MenuFlyoutItem Text="Help"
                Command="{Binding HelpCommand}">
    <MenuFlyoutItem.KeyboardAccelerators>
        <!-- Alternatively, 112 can be used to specify F1 on Windows -->
        <KeyboardAccelerator Modifiers="None"
                             Key="{OnPlatform MacCatalyst=UIKeyInputF1, WinUI=F1}" />
    </MenuFlyoutItem.KeyboardAccelerators>
</MenuFlyoutItem>

在此示例中，键盘快捷键是 F1 键，它通过两个平台上的常数指定。在 Windows 上，它也可以由整数 112 指定。

本地化键盘快捷键

键盘快捷键可以通过 .NET 资源文件进行本地化。然后可以使用 x:Static 标记扩展检索已本地化的键：

<MenuFlyoutItem Text="Cut"
                Clicked="OnCutMenuFlyoutItemClicked">
    <MenuFlyoutItem.KeyboardAccelerators>
        <KeyboardAccelerator Modifiers="Ctrl"
                             Key="{x:Static local:AppResources.CutAcceleratorKey}" />
    </MenuFlyoutItem.KeyboardAccelerators>
</MenuFlyoutItem>

有关详细信息，请参阅本地化。

禁用键盘快捷键

MenuFlyoutItem 被禁用时，关联的键盘快捷键也会被禁用：

<MenuFlyoutItem Text="Cut"
                Clicked="OnCutMenuFlyoutItemClicked"
                IsEnabled="false">
    <MenuFlyoutItem.KeyboardAccelerators>
        <KeyboardAccelerator Modifiers="Ctrl"
                             Key="X" />
    </MenuFlyoutItem.KeyboardAccelerators>
</MenuFlyoutItem>

在此示例中，由于 MenuFlyoutItem 的 IsEnabled 属性被设置为 false，因此无法调用关联的 Ctrl+X 键盘快捷键。

Share via