Aceleradores de teclado

Los aceleradores de teclado son métodos abreviados de teclado que mejoran la facilidad de uso y accesibilidad de las aplicaciones de la interfaz de usuario de aplicaciones .NET Multi-platform App UI (.NET MAUI) en Mac Catalyst y Windows y proporcionan una manera intuitiva para que los usuarios invoquen acciones o comandos comunes sin tener que ir directamente a la interfaz de usuario de la aplicación.

Un acelerador de teclado está formado por dos componentes:

• Modificadores, que incluyen Shift, Ctrl y Alt.
• Teclas, que incluyen teclas alfanuméricas y teclas especiales.

En .NET MAUI, los aceleradores de teclado están asociados a comandos expuestos en menús y deben especificarse con el elemento de menú. En concreto, los aceleradores de teclado .NET MAUI se pueden adjuntar a los elementos de menú de la barra de menús de Mac Catalyst y Windows, y los elementos de menú en menús contextuales de Windows. Para más información sobre las barras de menú, consulta Mostrar una barra de menús en una aplicación de escritorio de .NET MAUI. Para obtener más información sobre los menús contextuales, consulta Visualización de un menú contextual en una aplicación de escritorio de .NET MAUI

En las capturas de pantalla siguientes se muestran los elementos de la barra de menús y los elementos de menú contextual que incluyen aceleradores de teclado:

Un acelerador de teclado se representa mediante la clase KeyboardAccelerator, que representa una tecla de método abreviado para MenuFlyoutItem La clase KeyboardAccelerator define las propiedades siguientes:

• Modifiers, de tipo KeyboardAcceleratorModifiers, que representa el valor modificador, como Ctrl o Mayús, para el método abreviado de teclado.
• Key, de tipo string?, que representa el valor de la tecla para el método abreviado de teclado.

Estas propiedades están respaldadas por objetos BindableProperty, lo que significa que pueden ser destinos de los enlaces de datos.

La enumeración KeyboardAcceleratorModifiers define los siguientes miembros que se usan como valores para la propiedad Modifiers:

• None, que indica que no hay ningún modificador.
• Shift, que indica el modificador Shift en Mac Catalyst y Windows.
• Ctrl, que indica el modificador Control en Mac Catalyst y Windows.
• Alt, que indica el modificador Option en Mac Catalyst y el modificador Menu en Windows.
• Cmd, que indica el modificador Command en Mac Catalyst.
• Windows, que indica el modificador Windows en Windows.

Importante

Los aceleradores de teclado se pueden adjuntar a objetos MenuFlyoutItem de MenuBarItem en Mac Catalyst y Windows, y en MenuFlyout en Windows.

En la tabla siguiente se describen los formatos de acelerador de teclado compatibles con .NET MAUI:

Plataforma	Clave única	Varias claves
Mac Catalyst	Aceleradores de teclado sin un modificador, con una sola tecla. Por ejemplo, con la tecla F1 para invocar la acción asociada a un elemento de menú.	Aceleradores de teclado con uno o varios modificadores, con una sola tecla. Por ejemplo, con CMD+SHIFT+S or CMD+S para invocar la acción asociada a un elemento de menú.
Windows	Aceleradores de teclado con y sin un modificador, con una sola tecla. Por ejemplo, con la tecla F1 para invocar la acción asociada a un elemento de menú.	Aceleradores de teclado con uno o varios modificadores, con una sola tecla. Por ejemplo, con CTRL+SHIFT+F or CTRL+F para invocar la acción asociada a un elemento de menú.

Creación de un acelerador del teclado

KeyboardAccelerator se puede adjuntar a un elemento MenuFlyoutItem agregándolo a su colección KeyboardAccelerators:

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

Los aceleradores de teclado también se pueden especificar en código:

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

Cuando se presiona un modificador del acelerador de teclado y una tecla, se invoca la acción asociada a MenuFlyoutItem.

Importante

Aunque se pueden agregar varios objetos KeyboardAccelerator a la colección MenuFlyoutItem.KeyboardAccelerators, solo el primer objeto KeyboardAccelerator de la colección tendrá su acceso directo que aparezca en MenuFlyoutItem. Además, en Mac Catalyst, solo el método abreviado de teclado para el primer KeyboardAccelerator de la colección hará que se invoque la acción asociada a MenuFlyoutItem. Pero en Windows, los métodos abreviados de teclado para todos los objetos KeyboardAccelerator de la colección MenuFlyoutItem.KeyboardAccelerators harán que se invoque la acción MenuFlyoutItem.

Especificar varios modificadores

Se pueden especificar varios modificadores en KeyboardAccelerator en ambas plataformas:

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

El código de C# equivalente es el siguiente:

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

Especificar aceleradores de teclado por plataforma

Se pueden especificar distintos modificadores y teclas del acelerador de teclado por plataforma en XAML con la OnPlatform extensión de incremento:

<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>

El código de C# equivalente es el siguiente:

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
});

Usar teclas especiales en un acelerador de teclado

En Windows, se pueden especificar teclas especiales a través de una constante de cadena o con un entero. Para obtener una lista de constantes y enteros, consulta la tabla en VirtualKey.

Nota:

En Windows, se admiten aceleradores de teclas únicas (todas las teclas alfanuméricas y de puntuación, Supr, F2, Barra espaciadora, Esc, Tecla multimedia) y aceleradores de varias teclas (Ctrl+Mayús+M). Pero no se admiten las teclas virtuales del Controlador para juegos.

En Mac Catalyst, se pueden especificar teclas especiales a través de una constante de cadena. Para obtener una lista de constantes que representan las cadenas de entrada de texto que corresponden a teclas especiales, consulta Input strings for special keys (Cadenas de entrada para teclas especiales) en developer.apple.com.

En el código XAML siguiente se muestra un ejemplo de definición de un acelerador de teclado que usa una tecla especial:

<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>

En este ejemplo, el acelerador de teclado es la tecla F1, que se especifica a través de una constante en ambas plataformas. En Windows, también podría especificarse con el entero 112.

Localizar un acelerador de teclado

Las teclas de aceleración de teclado se pueden localizar a través de un archivo de recursos de .NET. Posteriormente, la tecla localizada se puede recuperar mediante la extensión de marcado x:Static:

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

Para más información, consulte Localización.

Deshabilitar un acelerador de teclado

Cuando se deshabilita MenuFlyoutItem, el acelerador de teclado asociado también se deshabilita:

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

En este ejemplo, dado que la IsEnabled propiedad de MenuFlyoutItem está establecida en false, no se puede invocar el acelerador de teclado CTRL+X asociado.