Movimento

L'interfaccia utente dell'app multipiattaforma .NET (.NET MAUI) Entry consente di immettere e modificare una singola riga di testo. Inoltre, Entry può essere usato come campo password.

Entry definisce le proprietà seguenti:

• ClearButtonVisibility, di tipo ClearButtonVisibility, controlla se viene visualizzato un pulsante non crittografato, che consente all'utente di cancellare il testo. Il valore predefinito di questa proprietà garantisce che non venga visualizzato un pulsante non crittografato.
• HorizontalTextAlignment, di tipo TextAlignment, definisce l'allineamento orizzontale del testo.
• IsPassword, di tipo bool, specifica se la voce deve nascondere visivamente il testo tipizzato.
• ReturnCommand, di tipo ICommand, definisce il comando da eseguire quando viene premuto il tasto restituito.
• ReturnCommandParameter, di tipo object, specifica il parametro per .ReturnCommand
• ReturnType, di tipo ReturnType, specifica l'aspetto del pulsante restituito.
• VerticalTextAlignment, di tipo TextAlignment, definisce l'allineamento verticale del testo.

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

Definisce inoltre Entry un Completed evento, che viene generato quando l'utente finalizza il testo in Entry con la chiave restituita.

Entry deriva dalla InputView classe da cui eredita le proprietà seguenti:

• CharacterSpacing, di tipo double, imposta la spaziatura tra i caratteri nel testo immesso.
• CursorPosition, di tipo int, definisce la posizione del cursore all'interno dell'editor.
• FontAttributes, di tipo FontAttributes, determina lo stile del testo.
• FontAutoScalingEnabled, di tipo bool, definisce se il testo rifletterà le preferenze di ridimensionamento impostate nel sistema operativo. Il valore predefinito di questa proprietà è true.
• FontFamily, di tipo string, definisce la famiglia di caratteri.
• FontSize, di tipo double, definisce le dimensioni del carattere.
• IsReadOnly, di tipo bool, definisce se l'utente deve essere impedito di modificare il testo. Il valore predefinito di questa proprietà è false.
• IsSpellCheckEnabled, di tipo bool, controlla se il controllo ortografico è abilitato.
• IsTextPredictionEnabled, di tipo bool, controlla se è abilitata la stima del testo e la correzione automatica del testo.
• Keyboard, di tipo Keyboard, specifica la tastiera di input soft visualizzata quando si immette testo.
• MaxLength, di tipo int, definisce la lunghezza massima di input.
• Placeholder, di tipo string, definisce il testo visualizzato quando il controllo è vuoto.
• PlaceholderColor, di tipo Color, definisce il colore del testo segnaposto.
• SelectionLength, di tipo int, rappresenta la lunghezza del testo selezionato all'interno del controllo .
• Text, di tipo string, definisce il testo immesso nel controllo .
• TextColor, di tipo Color, definisce il colore del testo immesso.
• TextTransform, di tipo TextTransform, specifica la combinazione di maiuscole e minuscole del testo immesso.

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

Definisce inoltre InputView un TextChanged evento, che viene generato quando il testo nelle Entry modifiche. L'oggetto TextChangedEventArgs che accompagna l'evento TextChanged ha NewTextValue proprietà e OldTextValue , che specificano rispettivamente il testo nuovo e precedente.

Per informazioni sulla specifica dei tipi di carattere in un Entryoggetto , vedere Tipi di carattere.

Creare una voce

Nell'esempio seguente viene illustrato come creare un oggetto Entry:

<Entry x:Name="entry"
       Placeholder="Enter text"
       TextChanged="OnEntryTextChanged"
       Completed="OnEntryCompleted" />

Il codice C# equivalente è il seguente:

Entry entry = new Entry { Placeholder = "Enter text" };
entry.TextChanged += OnEntryTextChanged;
entry.Completed += OnEntryCompleted;

Lo screenshot seguente mostra il risultato Entry in Android:

Nota

In iOS, la tastiera di input flessibile può coprire un campo di input di testo quando il campo si trova vicino alla parte inferiore dello schermo, rendendo difficile l'immissione di testo. Tuttavia, in un'app .NET MAUI iOS, le pagine scorrono automaticamente quando la tastiera di input flessibile copriva un campo di immissione di testo, in modo che il campo si trova sopra la tastiera di input soft. Il KeyboardAutoManagerScroll.Disconnect metodo, nello spazio dei Microsoft.Maui.Platform nomi , può essere chiamato per disabilitare questo comportamento predefinito. Il KeyboardAutoManagerScroll.Connect metodo può essere chiamato per riabilitare il comportamento dopo che è stato disabilitato.

È possibile accedere al testo immesso leggendo la Text proprietà e gli TextChanged eventi e Completed indicano che il testo è stato modificato o completato.

L'evento TextChanged viene generato quando il testo nelle Entry modifiche e specifica TextChangedEventArgs il testo prima e dopo la modifica tramite le OldTextValue proprietà e NewTextValue :

void OnEntryTextChanged(object sender, TextChangedEventArgs e)
{
    string oldText = e.OldTextValue;
    string newText = e.NewTextValue;
    string myText = entry.Text;
}

L'evento Completed viene generato quando l'utente ha terminato l'input premendo il tasto Invio sulla tastiera o premendo tabulazioni in Windows. Il gestore per l'evento è un gestore eventi generico:

void OnEntryCompleted(object sender, EventArgs e)
{
   string text = ((Entry)sender).Text;
}

Dopo che l'evento Completed viene generato, viene eseguito qualsiasi ICommand oggetto specificato dalla ReturnCommand proprietà , con l'oggetto object specificato dalla ReturnCommandParameter proprietà passata all'oggetto ReturnCommand.

Nota

La VisualElement classe, che si trova nella gerarchia di Entry ereditarietà, ha Focused anche eventi ed Unfocused .

Impostare la spaziatura dei caratteri

La spaziatura dei caratteri può essere applicata a un Entry oggetto impostando la CharacterSpacing proprietà su un double valore:

<Entry ...
       CharacterSpacing="10" />

Il risultato è che i caratteri nel testo visualizzato da Entry sono unità indipendenti dal dispositivo distanziate CharacterSpacing .

Nota

Il valore della CharacterSpacing proprietà viene applicato al testo visualizzato dalle Text proprietà e Placeholder .

Limitare la lunghezza dell'input

La MaxLength proprietà può essere utilizzata per limitare la lunghezza di input consentita per .Entry Questa proprietà deve essere impostata su un numero intero positivo:

<Entry ...
       MaxLength="10" />

Un MaxLength valore della proprietà 0 indica che non sarà consentito alcun input e un valore di int.MaxValue, ovvero il valore predefinito per un Entryoggetto , indica che non esiste alcun limite effettivo per il numero di caratteri che possono essere immessi.

Impostare la posizione del cursore e la lunghezza della selezione del testo

La CursorPosition proprietà può essere utilizzata per restituire o impostare la posizione in cui verrà inserito il carattere successivo nella stringa archiviata nella Text proprietà :

<Entry Text="Cursor position set"
       CursorPosition="5" />

Il valore predefinito della CursorPosition proprietà è 0, che indica che il testo verrà inserito all'inizio di Entry.

Inoltre, la SelectionLength proprietà può essere usata per restituire o impostare la lunghezza della selezione di testo all'interno di Entry:

<Entry Text="Cursor position and selection length set"
       CursorPosition="2"
       SelectionLength="10" />

Il valore predefinito della SelectionLength proprietà è 0, che indica che non è selezionato alcun testo.

Visualizzare un pulsante di cancellazione

La ClearButtonVisibility proprietà può essere utilizzata per controllare se un oggetto Entry visualizza un pulsante di cancellazione, che consente all'utente di cancellare il testo. Questa proprietà deve essere impostata su un ClearButtonVisibility membro di enumerazione:

• Never indica che un pulsante di cancellazione non verrà mai visualizzato. È il valore predefinito per la proprietà ClearButtonVisibility.
• WhileEditing indica che un pulsante di cancellazione verrà visualizzato in Entry, mentre ha lo stato attivo e il testo.

Nell'esempio seguente viene illustrata l'impostazione della proprietà :

<Entry Text=".NET MAUI"
       ClearButtonVisibility="WhileEditing" />

Lo screenshot seguente mostra un in Entry Android con il pulsante deselezionato abilitato:

Trasformare il testo

Un Entry oggetto può trasformare la combinazione di maiuscole e minuscole del testo archiviato nella Text proprietà impostando la TextTransform proprietà su un valore dell'enumerazione TextTransform . Questa enumerazione ha quattro valori:

• None indica che il testo non verrà trasformato.
• Default indica che verrà usato il comportamento predefinito per la piattaforma. Questo è il valore predefinito per la proprietà TextTransform.
• Lowercase indica che il testo verrà trasformato in minuscolo.
• Uppercase indica che il testo verrà trasformato in maiuscolo.

L'esempio seguente illustra la trasformazione del testo in maiuscolo:

<Entry Text="This text will be displayed in uppercase."
       TextTransform="Uppercase" />

Voce di testo oscura

Entry fornisce la IsPassword proprietà che nasconde visivamente il testo immesso quando è impostato su true:

<Entry IsPassword="true" />

Lo screenshot seguente mostra un oggetto Entry il cui input è stato nascosto:

Personalizzare la tastiera

La tastiera di input soft presentata quando gli utenti interagiscono con un Entry oggetto possono essere impostate a livello di codice tramite la Keyboard proprietà , su una delle proprietà seguenti della Keyboard classe :

• Chat - usata per messaggi di testo e posizioni in cui sono utili gli emoji.
• Default - tastiera predefinita.
• Email - usata per l'immissione di indirizzi di posta elettronica.
• Numeric - usata per l'immissione di numeri.
• Plain - usata per l'immissione di testo, senza KeyboardFlags specificati.
• Telephone - usata per l'immissione di numeri di telefono.
• Text - usata per l'immissione di testo.
• Url - usata per l'immissione di percorsi di file e indirizzi Web.

Nell'esempio seguente viene illustrata l'impostazione della Keyboard proprietà :

<Entry Keyboard="Chat" />

La classe Keyboard include anche un metodo factory Create che può essere usato per personalizzare una tastiera, specificando il comportamento di maiuscole/minuscole, controllo ortografico e suggerimenti. I valori di enumerazione KeyboardFlags vengono specificati come argomenti del metodo, con la restituzione di un elemento Keyboard personalizzato. L'enumerazione KeyboardFlags contiene i valori seguenti:

• None - non vengono aggiunte funzionalità alla tastiera.
• CapitalizeSentence - indica che la prima lettera della prima parola di ogni frase immessa verrà automaticamente scritta in maiuscolo.
• Spellcheck - indica che verrà eseguito il controllo ortografico sul testo immesso.
• Suggestions – indica che verranno offerti completamenti di parole per il testo immesso.
• CapitalizeWord - indica che la prima lettera di ogni parola verrà automaticamente scritta in maiuscolo.
• CapitalizeCharacter - indica che ogni carattere verrà scritto automaticamente in maiuscolo.
• CapitalizeNone - indica che non verrà applicata automaticamente la conversione in maiuscolo.
• All - indica che il controllo ortografico, i completamenti delle parole e la conversione in maiuscolo per le frasi verranno applicati al testo immesso.

L'esempio di codice XAML seguente mostra come personalizzare l'elemento Keyboard predefinito per offrire i completamenti delle parole e convertire in maiuscolo tutti i caratteri immessi:

<Entry Placeholder="Enter text here">
    <Entry.Keyboard>
        <Keyboard x:FactoryMethod="Create">
            <x:Arguments>
                <KeyboardFlags>Suggestions,CapitalizeCharacter</KeyboardFlags>
            </x:Arguments>
        </Keyboard>
    </Entry.Keyboard>
</Entry>

Il codice C# equivalente è il seguente:

Entry entry = new Entry { Placeholder = "Enter text here" };
entry.Keyboard = Keyboard.Create(KeyboardFlags.Suggestions | KeyboardFlags.CapitalizeCharacter);

Personalizzare la chiave restituita

L'aspetto del tasto restituito sulla tastiera di input soft, che viene visualizzato quando un oggetto Entry ha lo stato attivo, può essere personalizzato impostando la ReturnType proprietà su un valore dell'enumerazione ReturnType :

• Default : indica che non è necessaria alcuna chiave restituita specifica e che verrà usata l'impostazione predefinita della piattaforma.
• Done – indica una chiave restituita "Done".
• Go : indica una chiave restituita "Go".
• Next : indica una chiave restituita "Avanti".
• Search : indica una chiave restituita "Cerca".
• Send : indica una chiave restituita "Invia".

L'esempio XAML seguente illustra come impostare la chiave restituita:

<Entry ReturnType="Send" />

Nota

L'aspetto esatto della chiave restituita dipende dalla piattaforma. In iOS la chiave restituita è un pulsante basato su testo. Tuttavia, in Android e Windows, il tasto restituito è un pulsante basato sull'icona.

Quando viene premuto il tasto Return , viene generato l'evento Completed e viene eseguito qualsiasi ICommand elemento specificato dalla ReturnCommand proprietà . Inoltre, qualsiasi object specificato dalla ReturnCommandParameter proprietà verrà passato a ICommand come parametro. Per altre informazioni sui comandi, vedere Comandi.

Nascondere e visualizzare la tastiera di input soft

La SoftInputExtensions classe, nello spazio dei Microsoft.Maui nomi , fornisce una serie di metodi di estensione che supportano l'interazione con la tastiera di input soft sui controlli che supportano l'input di testo. La classe definisce i metodi seguenti:

• IsSoftInputShowing, che verifica se il dispositivo mostra attualmente la tastiera di input soft.
• HideSoftInputAsync, che tenterà di nascondere la tastiera di input soft se è attualmente visualizzata.
• ShowSoftInputAsync, che tenterà di visualizzare la tastiera di input soft se è attualmente nascosta.

Nell'esempio seguente viene illustrato come nascondere la tastiera di input soft in un Entry oggetto denominato entry, se è attualmente visualizzato:

if (entry.IsSoftInputShowing())
    await entry.HideSoftInputAsync(System.Threading.CancellationToken.None);

Abilitare e disabilitare il controllo ortografico

La IsSpellCheckEnabled proprietà controlla se il controllo ortografico è abilitato. Per impostazione predefinita, la proprietà è impostata su true. Quando l'utente immette testo, vengono indicati errori di ortografia.

Tuttavia, per alcuni scenari di immissione di testo, ad esempio l'immissione di un nome utente, il controllo ortografico fornisce un'esperienza negativa e deve essere disabilitato impostando la IsSpellCheckEnabled proprietà su false:

<Entry ... IsSpellCheckEnabled="false" />

Nota

Quando la IsSpellCheckEnabled proprietà è impostata su falsee non viene usata una tastiera personalizzata, il correttore ortografico nativo verrà disabilitato. Tuttavia, se è stato impostato un oggetto Keyboard che disabilita il controllo ortografico, ad esempio Keyboard.Chat, la IsSpellCheckEnabled proprietà viene ignorata. Pertanto, la proprietà non può essere utilizzata per abilitare il controllo ortografico per un Keyboard oggetto che lo disabilita in modo esplicito.

Abilitare e disabilitare la stima del testo

La IsTextPredictionEnabled proprietà controlla se la stima del testo e la correzione automatica del testo sono abilitate. Per impostazione predefinita, la proprietà è impostata su true. Quando l'utente immette testo, vengono presentate stime delle parole.

Tuttavia, per alcuni scenari di immissione di testo, ad esempio l'immissione di un nome utente, la stima del testo e la correzione automatica del testo offrono un'esperienza negativa e devono essere disabilitate impostando la IsTextPredictionEnabled proprietà su false:

<Entry ... IsTextPredictionEnabled="false" />

Nota

Quando la IsTextPredictionEnabled proprietà è impostata su falsee non viene usata una tastiera personalizzata, la stima del testo e la correzione automatica del testo sono disabilitate. Tuttavia, se è stato impostato un oggetto Keyboard che disabilita la stima del testo, la IsTextPredictionEnabled proprietà viene ignorata. Pertanto, la proprietà non può essere utilizzata per abilitare la stima del testo per un oggetto Keyboard che la disabilita in modo esplicito.

Impedire la voce di testo

È possibile impedire agli utenti di modificare il testo in un Entry oggetto impostando la IsReadOnly proprietà su true:

<Entry Text="User input won't be accepted."
       IsReadOnly="true" />

Nota

La IsReadonly proprietà non modifica l'aspetto visivo di un oggetto Entry, a differenza della IsEnabled proprietà che modifica anche l'aspetto visivo dell'oggetto in Entry grigio.