Aceleradores de teclado

Os aceleradores de teclado são atalhos de teclado que melhoram a usabilidade e a acessibilidade de seus aplicativos .NET Multi-platform App UI (.NET MAUI) no Mac, Catalyst e Windows, fornecendo uma maneira intuitiva para os usuários invocarem ações ou comandos comuns sem navegar diretamente na interface do usuário do aplicativo.

Um acelerador de teclado é composto por dois componentes:

• Modificadores, que incluem Shift, Ctrl e Alt.
• Chaves, que incluem chaves alfanuméricas e chaves especiais.

No .NET MAUI, os aceleradores de teclado são associados a comandos expostos em menus e devem ser especificados com o item de menu. Especificamente, os aceleradores de teclado .NET MAUI podem ser anexados a itens de menu na barra de menus no Mac Catalyst e no Windows e itens de menu nos menus de contexto no Windows. Para obter mais informações sobre barras de menus, consulte Exibir uma barra de menus em um aplicativo de área de trabalho .NET MAUI. Para obter mais informações sobre menus de contexto, consulte Exibir um menu de contexto em um aplicativo de área de trabalho .NET MAUI.

As capturas de tela a seguir mostram itens da barra de menus e itens de menu de contexto que incluem aceleradores de teclado:

Um acelerador de teclado é representado pela KeyboardAccelerator classe, que representa uma tecla de atalho para um MenuFlyoutItemarquivo . A KeyboardAccelerator classe define as seguintes propriedades:

• Modifiers, do tipo KeyboardAcceleratorModifiers, que representa o valor modificador, como Ctrl ou Shift, para o atalho de teclado.
• Key, do tipo string?, que representa o valor da tecla para o atalho de teclado.

Essas propriedades são apoiadas por BindableProperty objetos, o que significa que eles podem ser alvos de associações de dados.

A KeyboardAcceleratorModifiers enumeração define os seguintes membros que devem ser usados como valores para a Modifiers propriedade:

• None, que indica nenhum modificador.
• Shift, que indica o modificador Shift no Mac Catalyst e no Windows.
• Ctrl, que indica o modificador Control no Mac Catalyst e no Windows.
• Alt, que indica o modificador Opção no Mac Catalyst e o modificador Menu no Windows.
• Cmd, que indica o modificador de comando no Mac Catalyst.
• Windows, que indica o modificador do Windows no Windows.

Importante

Os aceleradores de teclado podem ser anexados a MenuFlyoutItem objetos em um Mac Catalyst e Windows e em um MenuBarItem MenuFlyout no Windows.

A tabela a seguir descreve os formatos do acelerador de teclado suportados pelo .NET MAUI:

Plataforma	Chave única	Multi-chave
Mac Catalyst	Aceleradores de teclado sem modificador, com uma única tecla. Por exemplo, usando a tecla F1 para invocar a ação associada a um item de menu.	Aceleradores de teclado com um ou mais modificadores, com uma única tecla. Por exemplo, usando CMD+SHIFT+S ou CMD+S para invocar a ação associada a um item de menu.
Windows	Aceleradores de teclado com e sem modificador, com uma única tecla. Por exemplo, usando a tecla F1 para invocar a ação associada a um item de menu.	Aceleradores de teclado com um ou mais modificadores, com uma única tecla. Por exemplo, usando CTRL+SHIFT+F ou CTRL+F para invocar a ação associada a um item de menu.

Criar um acelerador de teclado

A KeyboardAccelerator pode ser anexado a um MenuFlyoutItem adicionando-o à sua KeyboardAccelerators coleção:

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

Os aceleradores de teclado também podem ser especificados no código:

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

Quando um modificador do acelerador de teclado e uma tecla são pressionados, a ação associada ao MenuFlyoutItem é chamada.

Importante

Embora vários KeyboardAccelerator objetos possam ser adicionados à MenuFlyoutItem.KeyboardAccelerators coleção, somente o primeiro KeyboardAccelerator da coleção terá seu atalho exibido no MenuFlyoutItem. Além disso, no Mac Catalyst, somente o atalho de teclado para o primeiro KeyboardAccelerator da coleção fará com que a ação associada ao MenuFlyoutItem seja invocada. No entanto, no Windows, os atalhos de teclado para todos os KeyboardAccelerator objetos na MenuFlyoutItem.KeyboardAccelerators coleção farão com que a MenuFlyoutItem ação seja invocada.

Especificar vários modificadores

Vários modificadores podem ser especificados em um KeyboardAccelerator em ambas as plataformas:

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

Este é o código C# equivalente:

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

Especificar aceleradores de teclado por plataforma

Diferentes modificadores e teclas do acelerador de teclado podem ser especificados por plataforma em XAML com a OnPlatform extensão de marcação:

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

Este é o código C# equivalente:

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 especiais em um acelerador de teclado

No Windows, as teclas especiais podem ser especificadas por meio de uma constante de cadeia de caracteres ou com um inteiro. Para obter uma lista de constantes e inteiros, consulte a tabela em VirtualKey.

Observação

No Windows, há suporte para aceleradores de tecla única (todas as teclas alfanuméricas e de pontuação, Delete, F2, Barra de espaço, Esc, tecla multimídia) e aceleradores de várias teclas (Ctrl+Shift+M). No entanto, as teclas virtuais do Gamepad não são suportadas.

No Mac Catalyst, as teclas especiais podem ser especificadas por meio de uma constante de cadeia de caracteres. Para obter uma lista de constantes que representam as cadeias de caracteres de entrada de texto que correspondem a chaves especiais, consulte Cadeias de caracteres de entrada para chaves especiais em developer.apple.com.

O XAML a seguir mostra um exemplo de definição de um acelerador de teclado que usa uma 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>

Neste exemplo, o acelerador de teclado é a tecla F1, que é especificada por meio de uma constante em ambas as plataformas. No Windows, ele também pode ser especificado pelo inteiro 112.

Localizar um acelerador de teclado

As teclas de aceleração do teclado podem ser localizadas por meio de um arquivo de recurso .NET. A chave localizada pode ser recuperada usando a x:Static extensão de marcação:

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

Para obter mais informações, consulte Localização.

Desativar um acelerador de teclado

Quando um MenuFlyoutItem é desabilitado, o acelerador de teclado associado também é desabilitado:

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

Neste exemplo, como a IsEnabled propriedade do está definida como false, o acelerador de MenuFlyoutItem teclado CTRL+X associado não pode ser invocado.