Entrée

L’Entry de l’interface utilisateur de l’application multiplateforme .NET (.NET MAUI) vous permet d’entrer et de modifier une ligne de texte unique. En outre, l’Entry peut être utilisée comme champ de mot de passe.

Entry définit les propriétés suivantes :

• ClearButtonVisibility, de type ClearButtonVisibility, contrôle si un bouton Effacer est affiché, ce qui permet à l’utilisateur d’effacer le texte. La valeur par défaut de cette propriété garantit qu’aucun bouton Effacer n’est affiché.
• HorizontalTextAlignment, de type TextAlignment, définit l’alignement horizontal du texte.
• IsPassword, de type bool, spécifie si l’entrée doit masquer visuellement le texte tapé.
• ReturnCommand, de type ICommand, définit la commande à exécuter lorsque la touche de retour est enfoncée.
• ReturnCommandParameter, de type object, spécifie le paramètre pour la ReturnCommand.
• ReturnType, de type ReturnType, spécifie l’apparence du bouton de retour.
• VerticalTextAlignment, de type TextAlignment, définit l’alignement vertical du texte.

Les propriétés s’appuient sur des objets BindableProperty, ce qui signifie qu’elles peuvent être les cibles de liaisons de données et mises en forme avec un style.

En outre, l’Entry définit un évènement Completed, qui est déclenché lorsque l’utilisateur finalise le texte dans l’Entry avec la touche de retour.

L’Entry dérive de la classe InputView, depuis laquelle elle hérite des propriétés suivantes :

• CharacterSpacing, de type double, définit l’espacement entre les caractères dans le texte entré.
• CursorPosition, de type int, définit la position du curseur dans l’éditeur.
• FontAttributes, de type FontAttributes, détermine le style de texte.
• FontAutoScalingEnabled, de type bool, définit si le texte reflète ou non les préférences de mise à l’échelle définies dans le système d’exploitation. La valeur par défaut de cette propriété est true.
• FontFamily, de type string, définit la famille de police.
• FontSize, de type double, définit la taille de police.
• IsReadOnly, de type bool, définit si l’utilisateur doit être empêché de modifier le texte. La valeur par défaut de cette propriété est false.
• IsSpellCheckEnabled, de type bool, contrôle si la vérification orthographique est activée.
• IsTextPredictionEnabled, de type bool, contrôle si la prédiction de texte et la correction automatique du texte sont activées.
• Keyboard, de type Keyboard, spécifie le clavier logiciel affiché lors de la saisie de texte.
• MaxLength, de type int, définit la longueur d’entrée maximale.
• Placeholder, de type string, définit le texte affiché lorsque le contrôle est vide.
• PlaceholderColor, de type Color, définit la couleur du texte de l’espace réservé.
• SelectionLength, de type int, représente la longueur du texte sélectionné dans le contrôle.
• Text, de type string, définit le texte entré dans le contrôle.
• TextColor, de type Color, définit la couleur du texte entré.
• TextTransform, de type TextTransform, spécifie la casse du texte entré.

Les propriétés s’appuient sur des objets BindableProperty, ce qui signifie qu’elles peuvent être les cibles de liaisons de données et mises en forme avec un style.

En outre, l’InputView définit un évènement TextChanged, qui est déclenché lorsque le texte dans l’Entry change. L’objet TextChangedEventArgs qui accompagne l’évènement TextChanged a les propriétés NewTextValue et OldTextValue, qui spécifient respectivement le nouveau et l’ancien texte.

Pour plus d’informations sur la spécification des polices sur un Entry, consultez Polices.

Créer une entrée

L’exemple suivant montre comment créer un Entry :

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

Le code C# équivalent est :

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

La capture d’écran suivante montre l’Entry résultante sur Android :

Remarque

Sur iOS, le clavier logiciel peut couvrir un champ d’entrée de texte lorsque celui-ci se trouve près du bas de l’écran, ce qui rend difficile l’entrée de texte. Toutefois, dans une application iOS .NET MAUI, les pages défilent automatiquement lorsque le clavier logiciel couvre un champ d’entrée de texte, de sorte que le champ se trouve au-dessus du clavier logiciel. La méthode KeyboardAutoManagerScroll.Disconnect, dans l’espace de noms Microsoft.Maui.Platform, peut être appelée pour désactiver ce comportement par défaut. La méthode KeyboardAutoManagerScroll.Connect peut être appelée pour réactiver le comportement après sa désactivation.

Le texte entré est accessible en lisant la propriété Text, et les évènements TextChanged et Completed signalent que le texte a changé ou a été terminé.

L’évènement TextChanged est déclenché lorsque le texte dans l’Entry change, et TextChangedEventArgs fournit le texte avant et après la modification via les propriétés OldTextValue et NewTextValue :

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

L’évènement Completed est déclenché lorsque l’utilisateur a terminé l’entrée en appuyant sur la touche Retour du clavier ou en appuyant sur la touche Tab sur Windows. Le gestionnaire de l’évènement est un gestionnaire d’évènements générique :

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

Une fois l’événement Completed déclenché, toute ICommand spécifiée par la propriété ReturnCommand est exécutée, l’object spécifié par la propriété ReturnCommandParameter étant transmis à la ReturnCommand.

Remarque

La classe VisualElement, qui se trouve dans la hiérarchie d’héritage Entry, a également des évènements Focused et Unfocused.

Définir l’espacement des caractères

L’espacement des caractères peut être appliqué à une Entry en définissant la propriété CharacterSpacing sur une valeur double :

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

Le résultat est que les caractères du texte affiché par l’Entry sont espacés de CharacterSpacing unités indépendantes de l’appareil.

Remarque

La valeur de la propriété CharacterSpacingest appliquée au texte affiché par les propriétés Text et Placeholder.

Limiter la longueur d’entrée

La propriété MaxLength peut être utilisée pour limiter la longueur d’entrée autorisée pour l’Entry. Cette propriété doit être définie sur un entier positif :

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

Une valeur de propriété MaxLength de 0 indique qu’aucune entrée n’est autorisée, et une valeur de int.MaxValue, qui est la valeur par défaut d’une Entry, indique qu’il n’existe aucune limite effective sur le nombre de caractères pouvant être entrés.

Définir la position du curseur et la longueur de sélection du texte

La propriété CursorPosition peut être utilisée pour retourner ou définir la position à laquelle le caractère suivant sera inséré dans la chaîne stockée dans la propriété Text :

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

La valeur par défaut de la propriété CursorPosition est 0, ce qui indique que le texte sera inséré au début de l’Entry.

En outre, la propriété SelectionLength peut être utilisée pour retourner ou définir la longueur de la sélection de texte dans l’Entry :

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

La valeur par défaut de la propriété SelectionLength est 0, ce qui indique qu’aucun texte n’est sélectionné.

Afficher un bouton Effacer

La propriété ClearButtonVisibility peut être utilisée pour contrôler si une Entry affiche un bouton Effacer, ce qui permet à l’utilisateur d’effacer le texte. Cette propriété doit être définie sur un membre de l’énumération ClearButtonVisibility :

• Never indique qu’aucun bouton Effacer ne sera jamais affiché. Il s'agit de la valeur par défaut de la propriété ClearButtonVisibility.
• WhileEditing indique qu’un bouton Effacer s’affichera dans l’Entry, alors qu’elle a le focus et le texte.

L’exemple suivant montre comment définir la propriété :

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

La capture d’écran suivante montre une Entry sur Android avec le bouton Effacer activé :

Transformer le texte

Une Entry peut transformer la casse de son texte, stockée dans la propriété Text, en définissant la propriété TextTransform sur une valeur de l’énumération TextTransform. Cette énumération a quatre valeurs :

• None indique que le texte n’est pas transformé.
• Default indique que le comportement par défaut de la plateforme est utilisé. C’est la valeur par défaut de la propriété TextTransform.
• Lowercase indique que le texte est transformé en minuscules.
• Uppercase indique que le texte est transformé en majuscules.

L’exemple suivant montre comment transformer du texte en majuscules :

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

Masquer l’entrée de texte

L’Entry fournit la propriété IsPassword qui masque visuellement le texte entré lorsqu’elle est définie sur true:

<Entry IsPassword="true" />

La capture d’écran suivante montre une Entry dont la saisie a été masquée :

Personnaliser le clavier

Le clavier logiciel présenté lorsque les utilisateurs interagissent avec un Entry peut être défini de manière programmatique via la propriété Keyboard, sur l’une des propriétés suivantes de la classe Keyboard :

• Chat : utilisé pour envoyer des SMS et place les emojis là où ils sont utiles.
• Default : le raccourci clavier par défaut.
• Email : utilisé lorsque des adresses e-mail sont saisies.
• Numeric : utilisé lorsque des nombres sont saisis.
• Plain : utilisé lorsque du texte est saisi sans que des KeyboardFlags ne soient spécifiés.
• Telephone : utilisé lorsque des numéros de téléphone sont saisis.
• Text : utilisé lorsque du texte est saisi.
• Url : utilisé pour entrer des chemins d’accès de fichier et des URL.

L'exemple suivant présente la configuration de la propriété Keyboard :

<Entry Keyboard="Chat" />

La classe Keyboard dispose également d’une méthode de fabrique Create qui peut être utilisée pour personnaliser un clavier en spécifiant le comportement de mise en majuscules, de vérification orthographique et de suggestion. Les valeurs d’énumération KeyboardFlags sont spécifiées en tant qu’arguments pour la méthode en retournant un Keyboard personnalisé. L’énumération KeyboardFlags contient les valeurs suivantes :

• None : aucune fonctionnalité n’est ajoutée au clavier.
• CapitalizeSentence : indique que les premières lettres des premiers mots de chaque phrase saisie sont automatiquement mises en majuscules.
• Spellcheck : indique que la vérification orthographique sera effectuée sur le texte saisi.
• Suggestions : indique que la saisie semi-automatique des mots sera proposée pour le texte saisi.
• CapitalizeWord : indique que la première lettre de chaque mot est automatiquement mise en majuscules.
• CapitalizeCharacter : indique que tous les caractères sont automatiquement mis en majuscules.
• CapitalizeNone : indique qu’aucune lettre n’est mise en majuscules automatiquement.
• All : indique que la vérification orthographique, la saisie semi-automatique des mots et la mise en majuscules de la première lettre de la phrase seront appliquées au texte saisi.

L’exemple de code XAML suivant montre comment personnaliser le Keyboard par défaut afin de proposer des saisies semi-automatiques et de mettre en majuscules chaque caractère saisi :

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

Le code C# équivalent est :

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

Personnaliser la touche de retour

L’apparence de la touche de retour sur le clavier logiciel, qui s’affiche lorsqu’un Entry a le focus, peut être personnalisée en définissant la propriété ReturnType sur une valeur de l’énumération ReturnType :

• Default : indique qu’aucune touche de retour spécifique n’est requise et que le comportement par défaut de la plateforme sera utilisé.
• Done : indique une touche de retour « Terminé ».
• Go : indique une touche de retour « Aller ».
• Next : indique une touche de retour « Suivant ».
• Search : indique une touche de retour « Rechercher ».
• Send : indique une touche de retour « Envoyer ».

L’exemple XAML suivant montre comment définir la touche de retour :

<Entry ReturnType="Send" />

Remarque

L’apparence exacte de la touche de retour dépend de la plateforme. Sur iOS, la touche de retour est un bouton textuel. Cependant, sur Android et Windows, la touche de retour est un bouton basé sur une icône.

Lorsque la touche Retour est enfoncée, l’évènement Completed se déclenche et toute ICommand spécifiée par la propriété ReturnCommand est exécutée. En outre, tout object spécifié par la propriété ReturnCommandParameter est transmis à la propriété ICommand en tant que paramètre. Pour plus d’informations sur les commandes, consultez Commander.

Masquer et afficher le clavier logiciel

La classe SoftInputExtensions, dans l’espace de noms Microsoft.Maui, fournit une série de méthodes d’extension qui prennent en charge l’interaction avec le clavier logiciel sur les contrôles qui prennent en charge l’entrée de texte. La classe définit les méthodes suivantes :

• IsSoftInputShowing, qui vérifie si l’appareil affiche actuellement le clavier logiciel.
• HideSoftInputAsync, qui tentera de masquer le clavier logiciel s’il est actuellement affiché.
• ShowSoftInputAsync, qui tentera d’afficher le clavier d’entrée programmable s’il est actuellement masqué.

L’exemple suivant montre comment masquer le clavier logiciel sur un Entry appelé entry, s’il est actuellement affiché :

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

Activer et désactiver la vérification orthographique

La propriété IsSpellCheckEnabled contrôle si la vérification orthographique est activée. Par défaut, la propriété est définie sur true. Lorsque l’utilisateur entre du texte, les fautes d’orthographe sont indiquées.

Toutefois, pour certains scénarios d’entrée de texte, comme l’entrée d’un nom d’utilisateur, la vérification orthographique fournit une expérience négative et doit être désactivée en définissant la propriété IsSpellCheckEnabled sur false :

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

Remarque

Lorsque la propriété IsSpellCheckEnabled est définie sur false, et qu’un clavier personnalisé n’est pas utilisé, le vérificateur orthographique natif est désactivé. Toutefois, si un Keyboard a été défini qui désactive la vérification orthographique, comme Keyboard.Chat, la propriété IsSpellCheckEnabled est ignorée. Par conséquent, la propriété ne peut pas être utilisée pour activer la vérification orthographique pour un Keyboard qui la désactive explicitement.

Activer et désactiver la prédiction de texte

La propriété IsTextPredictionEnabled contrôle si la prédiction de texte et la correction automatique du texte sont activées. Par défaut, la propriété est définie sur true. Lorsque l’utilisateur entre du texte, des prédictions de mots sont présentées.

Toutefois, pour certains scénarios d’entrée de texte, tels que l’entrée d’un nom d’utilisateur, la prédiction de texte et la correction automatique du texte, offrent une expérience négative et doivent être désactivés en définissant la propriété IsTextPredictionEnabled sur false:

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

Remarque

Lorsque la propriété IsTextPredictionEnabled est définie sur false, et qu’un clavier personnalisé n’est pas utilisé, la prédiction de texte et la correction automatique du texte sont désactivées. Toutefois, si un Keyboard a été défini qui désactive la prédiction de texte, la propriété IsTextPredictionEnabled est ignorée. Par conséquent, la propriété ne peut pas être utilisée pour activer la prédiction de texte pour un Keyboard qui la désactive explicitement.

Empêcher l’entrée de texte

Les utilisateurs peuvent être empêchés de modifier le texte dans une Entry en définissant la propriété IsReadOnly sur true :

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

Remarque

La propriété IsReadonly ne modifie pas l’apparence visuelle d’une Entry, contrairement à la propriété IsEnabled qui modifie également l’apparence visuelle de la Entry en gris.