Akceleratory klawiatury

Akceleratory klawiaturowe to skróty klawiaturowe, które zwiększają użyteczność i dostępność aplikacji wieloplatformowych UI (.NET MAUI) na platformach Mac Catalyst i Windows, zapewniając intuicyjny sposób na prowadzenie typowych akcji lub poleceń bez bezpośredniego nawigowania po interfejsie użytkownika.

Akcelerator klawiatury składa się z dwóch składników:

• Modyfikatory, które obejmują Shift, Ctrl i Alt.
• Klucze, które obejmują klucze alfanumeryczne i klucze specjalne.

W programie .NET MAUI akceleratory klawiatury są skojarzone z poleceniami uwidocznianymi w menu i powinny być określone za pomocą elementu menu. W szczególności akceleratory klawiaturowe .NET MAUI można dołączyć do elementów menu na pasku menu na komputerach Mac Catalyst i Windows, a także do elementów menu w menu kontekstowych w systemie Windows. Aby uzyskać więcej informacji na temat pasków menu, zobacz Wyświetlanie paska menu w aplikacji klasycznej .NET MAUI. Aby uzyskać więcej informacji na temat menu kontekstowych, zobacz Wyświetlanie menu kontekstowego w aplikacji klasycznej .NET MAUI.

Na poniższych zrzutach ekranu przedstawiono elementy paska menu i elementy menu kontekstowego zawierające akceleratory klawiatury:

Akcelerator klawiatury jest reprezentowany przez klasę KeyboardAccelerator, która reprezentuje skrót klawiaturowy dla elementu MenuFlyoutItem. Klasa KeyboardAccelerator definiuje następujące właściwości:

• Modifiers, typu KeyboardAcceleratorModifiers, który reprezentuje wartość modyfikatora, taką jak Ctrl lub Shift, dla skrótu klawiaturowego.
• Key, typu string?, który reprezentuje wartość skrótu klawiaturowego.

Te właściwości są wspierane przez BindableProperty obiekty, co oznacza, że mogą być obiektami docelowymi powiązań danych.

Wyliczenie KeyboardAcceleratorModifiers definiuje następujących członków, którzy mogą być używani jako wartości dla właściwości Modifiers.

• None, który nie wskazuje modyfikatora.
• Shift, który wskazuje modyfikator Shift w Mac Catalyst i Windows.
• Ctrl, który wskazuje modyfikator sterowania na Mac Catalyst i Windows.
• Alt, który wskazuje modyfikator Option w Mac Catalyst i modyfikator Menu w systemie Windows.
• Cmd, który wskazuje modyfikator poleceń dla Mac Catalyst.
• Windows, który wskazuje modyfikator systemu Windows w systemie Windows.

Ważne

Akceleratory klawiatury można dołączać do MenuFlyoutItem obiektów na platformach Mac Catalyst i Windows w MenuBarItem, a także na Windows w MenuFlyout.

W poniższej tabeli przedstawiono formaty skrótów klawiatury obsługiwane przez program .NET MAUI:

Platforma	Pojedynczy klucz	Wiele kluczy
Mac Catalyst	Skróty klawiaturowe bez modyfikatora, za pomocą pojedynczego klawisza. Na przykład użycie F1 w celu wywołania akcji skojarzonej z elementem menu.	Akceleratory klawiatury z co najmniej jednym modyfikatorem. Na przykład użyj polecenia Cmd+Shift+S lub Cmd+S, aby wywołać akcję skojarzona z elementem menu.
Windows	Akceleratory klawiatury z modyfikatorem i bez niego, z pojedynczym klawiszem. Na przykład użycie F1 w celu wywołania akcji skojarzonej z elementem menu.	Akceleratory klawiatury z co najmniej jednym modyfikatorem, z pojedynczym klawiszem. Na przykład za pomocą Ctrl+Shift+F lub Ctrl+F w celu wywołania akcji skojarzonej z elementem menu.

Tworzenie akceleratora klawiatury

Element KeyboardAccelerator można dołączyć do obiektu MenuFlyoutItem , dodając go do kolekcji KeyboardAccelerators :

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

Akceleratory klawiatury można również określić w kodzie:

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

Po naciśnięciu modyfikatora akceleratora klawiatury i klawisza, wywoływana jest akcja skojarzona z MenuFlyoutItem.

Ważne

Chociaż do kolekcji MenuFlyoutItem.KeyboardAccelerators można dodać wiele KeyboardAccelerator obiektów, tylko pierwszy KeyboardAccelerator w kolekcji będzie miał swój skrót wyświetlany na MenuFlyoutItem. Ponadto na Komputerze Mac Catalyst tylko skrót klawiaturowy dla pierwszego KeyboardAccelerator w kolekcji spowoduje wywołanie akcji skojarzonej z elementem MenuFlyoutItem . Jednak w systemie Windows skróty klawiaturowe dla wszystkich KeyboardAccelerator obiektów w MenuFlyoutItem.KeyboardAccelerators kolekcji wywołają akcję MenuFlyoutItem.

Określanie wielu modyfikatorów

Na obu platformach można określić wiele modyfikatorów w KeyboardAccelerator.

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

Równoważny kod języka C# to:

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

Określanie akceleratorów klawiatury na platformę

Różne modyfikatory akceleratora klawiatury i klawisze można określić na różnych platformach w języku XAML za pomocą rozszerzenia znaczników OnPlatform.

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

Równoważny kod języka C# to:

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

Użyj specjalnych klawiszy w akceleratorze klawiatury

W systemie Windows klucze specjalne można określić za pomocą stałej tekstowej lub liczby całkowitej. Aby uzyskać listę stałych i liczb całkowitych, zobacz tabelę w pliku VirtualKey.

Uwaga / Notatka

W systemie Windows obsługiwane są pojedyncze akceleratory klawiszy (wszystkie alfanumeryczne i interpunkcyjne klawisze, Delete, F2, Spacja, Esc, klawisz multimedialny) oraz akceleratory wieloklawiszowe (Ctrl+Shift+M). Jednak klucze wirtualne gamepad nie są obsługiwane.

Na komputerze z systemem Mac Catalyst specjalne klucze można określić za pomocą stałej znakowej. Aby uzyskać listę stałych reprezentujących ciągi wejściowe tekstu, które odpowiadają specjalnym kluczom, zobacz Ciągi wejściowe dla kluczy specjalnych w developer.apple.com.

Poniższy kod XAML przedstawia przykład definiowania akceleratora klawiatury, który używa specjalnego klawisza.

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

W tym przykładzie skrót klawiszowy to klawisz F1, który jest określony za pomocą stałej dla obu platform. W systemie Windows można go również określić za pomocą liczby całkowitej 112.

Lokalizowanie akcleratora klawiatury

Klawisze akceleratora klawiatury można lokalizować przez plik zasobu platformy .NET. Następnie można pobrać zlokalizowany klucz przy użyciu x:Static rozszerzenia znaczników:

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

Aby uzyskać więcej informacji, zobacz Lokalizacja.

Wyłączanie akceleratora klawiatury

Gdy element MenuFlyoutItem jest wyłączony, skojarzony akcelerator klawiatury jest również wyłączony:

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

W tym przykładzie, ponieważ właściwość IsEnabled obiektu MenuFlyoutItem jest ustawiona na false, nie można wywołać skojarzonego akceleratora klawiatury Ctrl+X.