Acceleratori tramite tastiera

Gli acceleratori di tastiera sono tasti di scelta rapida che migliorano l'usabilità e l'accessibilità delle app .NET Multipiattaforma (.NET MAUI) in Mac Catalyst e Windows offrendo agli utenti un modo intuitivo per richiamare azioni o comandi comuni senza spostarsi direttamente nell'interfaccia utente dell'app.

Un acceleratore di tastiera è costituito da due componenti:

• Modificatori, che includono MAIUSC, CTRL e ALT.
• Chiavi, che includono chiavi alfanumerici e tasti speciali.

In .NET MAUI i tasti di scelta rapida sono associati ai comandi esposti nei menu e devono essere specificati con la voce di menu. In particolare, gli acceleratori di tastiera MAUI .NET possono essere collegati alle voci di menu nella barra dei menu in Mac Catalyst e Windows e voci di menu nei menu di scelta rapida in Windows. Per altre informazioni sulle barre dei menu, vedere Visualizzare una barra dei menu in un'app desktop MAUI .NET. Per altre informazioni sui menu di scelta rapida, vedere Visualizzare un menu di scelta rapida in un'app desktop MAUI .NET.

Gli screenshot seguenti mostrano le voci della barra dei menu e le voci del menu di scelta rapida che includono gli acceleratori di tastiera:

Un acceleratore di tastiera è rappresentato dalla KeyboardAccelerator classe , che rappresenta un tasto di scelta rapida per un oggetto MenuFlyoutItem. La KeyboardAccelerator classe definisce le proprietà seguenti:

• Modifiers, di tipo KeyboardAcceleratorModifiers, che rappresenta il valore del modificatore, ad esempio CTRL o MAIUSC, per la scelta rapida da tastiera.
• Key, di tipo string?, che rappresenta il valore del tasto per la scelta rapida da tastiera.

Queste proprietà sono supportate da BindableProperty oggetti, il che significa che possono essere destinazioni di data binding.

L'enumerazione KeyboardAcceleratorModifiers definisce i membri seguenti che devono essere utilizzati come valori per la Modifiers proprietà :

• None, che indica nessun modificatore.
• Shift, che indica il modificatore Shift in Mac Catalyst e Windows.
• Ctrl, che indica il modificatore di controllo in Mac Catalyst e Windows.
• Alt, che indica il modificatore option in Mac Catalyst e il modificatore menu in Windows.
• Cmd, che indica il modificatore command in Mac Catalyst.
• Windows, che indica il modificatore di Windows in Windows.

Importante

I tasti di scelta rapida possono essere collegati a MenuFlyoutItem oggetti in un MenuBarItem in Mac Catalyst e Windows e in un MenuFlyout in Windows.

La tabella seguente illustra i formati dell'acceleratore di tastiera supportati da .NET MAUI:

Piattaforma	Chiave singola	Multi-key
Mac Catalyst	Tasti di scelta rapida senza modificatore, con un singolo tasto. Ad esempio, usando il tasto F1 per richiamare l'azione associata a una voce di menu.	Tasti di scelta rapida con uno o più modificatori, con un singolo tasto. Ad esempio, usando CMD+MAIUSC+S o CMD+S per richiamare l'azione associata a una voce di menu.
Windows	Tasti di scelta rapida con e senza modificatore, con un singolo tasto. Ad esempio, usando il tasto F1 per richiamare l'azione associata a una voce di menu.	Tasti di scelta rapida con uno o più modificatori, con un singolo tasto. Ad esempio, usando CTRL+MAIUSC+F o CTRL+F per richiamare l'azione associata a una voce di menu.

Creare un acceleratore di tastiera

Un KeyboardAccelerator oggetto può essere associato a un MenuFlyoutItem oggetto aggiungendolo alla relativa KeyboardAccelerators raccolta:

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

I tasti di scelta rapida possono essere specificati anche nel codice:

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

Quando viene premuto un modificatore dell'acceleratore di tastiera e un tasto, viene richiamata l'azione associata a MenuFlyoutItem .

Importante

Anche se è possibile aggiungere più KeyboardAccelerator oggetti all'insieme MenuFlyoutItem.KeyboardAccelerators , solo il primo KeyboardAccelerator nella raccolta avrà il collegamento visualizzato in MenuFlyoutItem. Inoltre, in Mac Catalyst, solo la scelta rapida da tastiera per la prima KeyboardAccelerator nella raccolta causerà l'azione associata all'oggetto MenuFlyoutItem da richiamare. In Windows, tuttavia, i tasti di scelta rapida per tutti gli oggetti dell'insieme KeyboardAcceleratorMenuFlyoutItem.KeyboardAccelerators causeranno la chiamata dell'azione MenuFlyoutItem .

Specificare più modificatori

In entrambe le piattaforme è possibile specificare KeyboardAccelerator più modificatori:

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

Il codice C# equivalente è il seguente:

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

Specificare i tasti di scelta rapida per ogni piattaforma

È possibile specificare diversi modificatori e tasti dell'acceleratore di tastiera per ogni piattaforma in XAML con l'estensione di OnPlatform markup:

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

Il codice C# equivalente è il seguente:

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

Usare tasti speciali in un tasto di scelta rapida

In Windows è possibile specificare chiavi speciali tramite una costante stringa o con un numero intero. Per un elenco di costanti e numeri interi, vedere la tabella in VirtualKey.

Nota

In Windows sono supportati acceleratori a tasto singolo (tutti i tasti alfanumerici e di punteggiatura, Elimina, F2, Barra spaziatrice, Esc, Tasto multimediale) e tasti di scelta rapida multichiavi (CTRL+MAIUSC+M). Tuttavia, i tasti virtuali game pad non sono supportati.

In Mac Catalyst è possibile specificare chiavi speciali tramite una costante stringa. Per un elenco di costanti che rappresentano le stringhe di input di testo corrispondenti a chiavi speciali, vedere Stringhe di input per chiavi speciali in developer.apple.com.

Il codice XAML seguente mostra un esempio di definizione di un acceleratore di tastiera che usa un tasto speciale:

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

In questo esempio l'acceleratore della tastiera è il tasto F1, specificato tramite una costante in entrambe le piattaforme. In Windows, può anche essere specificato dall'intero 112.

Localizzare un accleratore da tastiera

I tasti di scelta rapida possono essere localizzati tramite un file di risorse .NET. La chiave localizzata può quindi essere recuperata usando l'estensione x:Static di markup:

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

Per altre informazioni, vedere Localizzazione.

Disabilitare un tasto di scelta rapida

Quando un oggetto MenuFlyoutItem è disabilitato, viene disabilitato anche l'acceleratore di tastiera associato:

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

In questo esempio, poiché la IsEnabled proprietà di MenuFlyoutItem è impostata su false, non è possibile richiamare l'acceleratore di tastiera CTRL+X associato.