Étiquette

  • Article

Parcourez l’exemple. Parcourir l'exemple

L’objet Label .NET Multi-Platform App UI (.NET MAUI) affiche du texte sur une ou plusieurs lignes. Le texte affiché par un Label peut être coloré, espacé et présenter des décorations de texte.

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

  • CharacterSpacing, de type double, définit l’espacement entre les caractères dans le texte affiché.
  • FontAttributes, de type FontAttributes, détermine le style du 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.
  • FormattedText, de type FormattedString, spécifie la présentation du texte avec plusieurs options de présentation telles que les polices et les couleurs.
  • HorizontalTextAlignment, de type TextAlignment, définit l’alignement horizontal du texte affiché.
  • LineBreakMode, de type LineBreakMode, détermine comment le texte doit être traité lorsqu’il ne peut pas tenir sur une ligne.
  • LineHeight, de type double, spécifie le multiplicateur à appliquer à la hauteur de ligne par défaut lors de l’affichage du texte.
  • MaxLines, de type int, indique le nombre maximal de lignes autorisées dans le Label.
  • Padding, de type Thickness, détermine le remplissage de l’étiquette.
  • Text, de type string, définit le texte affiché comme contenu de l’étiquette.
  • TextColor, de type Color, définit la couleur du texte affiché.
  • TextDecorations, de type TextDecorations, spécifie les décorations de texte (souligné et barré) qui peuvent être appliquées.
  • TextTransform, de type TextTransform, spécifie la casse du texte affiché.
  • TextType, de type TextType, détermine si le Label doit afficher du texte brut ou du texte HTML.
  • VerticalTextAlignment, de type TextAlignment, définit l’alignement vertical du texte affiché.

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.

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

Créer un objet Label

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

<Label Text="Hello world" />

Le code C# équivalent est :

Label label = new Label { Text = "Hello world" };

Définir des couleurs

Les objets Label peuvent être définis pour utiliser une couleur de texte spécifique via la propriété TextColor.

L’exemple suivant définit la couleur de texte d’un Label :

<Label TextColor="#77d065"
       Text="This is a green label." />

Pour plus d’informations sur les couleurs, consultez Couleurs.

Définir l’espacement des caractères

Un espacement des caractères peut être appliqué à des objets Label en définissant la propriété CharacterSpacing sur une valeur double :

<Label Text="Character spaced text"
       CharacterSpacing="10" />

Résultat : les caractères dans le texte affiché par le Label sont espacés de CharacterSpacing unités indépendantes de l’appareil.

Ajouter de nouvelles lignes

Il existe deux techniques principales pour forcer la saisie de texte dans un Label sur une nouvelle ligne, à partir de XAML :

  1. Utilisez le caractère de saut de ligne unicode, à savoir «   ».
  2. Spécifiez votre texte en utilisant la syntaxe d’un élément de propriété.

Le code suivant montre un exemple de ces deux techniques :

<!-- Unicode line feed character -->
<Label Text="First line &#10; Second line" />

<!-- Property element syntax -->
<Label>
    <Label.Text>
        First line
        Second line
    </Label.Text>
</Label>

En C#, la saisie de texte sur une nouvelle ligne peut être forcée avec le caractère « \n » :

Label label = new Label { Text = "First line\nSecond line" };

Contrôler la troncation du texte et le retour automatique à la ligne

Le retour automatique à la ligne et la troncation peuvent être contrôlés en attribuant à la propriété LineBreakMode une valeur de l’énumération LineBreakMode :

  • NoWrap : ne renvoie pas automatiquement le texte à la ligne ; affiche uniquement autant de texte que possible sur une même ligne. C’est la valeur par défaut de la propriété LineBreakMode.
  • WordWrap : renvoie automatiquement le texte à la ligne au niveau de la limite de mot.
  • CharacterWrap : renvoie automatiquement le texte sur une nouvelle ligne au niveau d’une limite de caractères.
  • HeadTruncation : tronque le début du texte et en affiche la fin.
  • MiddleTruncation : affiche le début et la fin du texte ; le milieu est remplacé par des points de suspension.
  • TailTruncation : affiche le début du texte et en tronque la fin.

Afficher un nombre spécifique de lignes

Le nombre de lignes affichées par un Label peut être spécifié en attribuant à la propriété MaxLines une valeur int :

  • Quand MaxLines est égal à -1, qui est sa valeur par défaut, le Label respecte la valeur de la propriété LineBreakMode pour afficher soit une seule ligne, éventuellement tronquée, soit toutes les lignes avec le texte complet.
  • Quand MaxLines est égal à 0, le Label ne s’affiche pas.
  • Quand MaxLines est égal à 1, cela revient à attribuer à la propriété LineBreakMode la valeur NoWrap, HeadTruncation, MiddleTruncation ou TailTruncation. Cependant, le Label respecte la valeur de la propriété LineBreakMode en ce qui concerne le placement des points de suspension, le cas échéant.
  • Quand MaxLines est supérieur à 1, le Label s’affiche jusqu’au nombre de lignes spécifié, tout en respectant la valeur de la propriété LineBreakMode en ce qui concerne le placement des points de suspension, le cas échéant. Toutefois, le fait d’attribuer à la propriété MaxLines une valeur supérieure à 1 n’a aucun effet si la propriété LineBreakMode est définie sur NoWrap.

L’exemple XAML suivant illustre la définition de la propriété MaxLines pour un Label :

<Label Text="Lorem ipsum dolor sit amet, consectetur adipiscing elit. In facilisis nulla eu felis fringilla vulputate. Nullam porta eleifend lacinia. Donec at iaculis tellus."
       LineBreakMode="WordWrap"
       MaxLines="2" />

Définir la hauteur de ligne

La hauteur verticale d’un Label peut être personnalisée en attribuant à la propriété Label.LineHeight une valeur double.

Remarque

  • Sur iOS, la propriété Label.LineHeight modifie la hauteur de ligne du texte qui tient sur une seule ligne et le texte est renvoyé automatiquement à la ligne sur plusieurs lignes.
  • Sur Android, la propriété Label.LineHeight modifie uniquement la hauteur de ligne du texte qui est renvoyé automatiquement à la ligne sur plusieurs lignes.
  • Sur Windows, la propriété Label.LineHeight modifie la hauteur de ligne du texte qui est renvoyé automatiquement à la ligne sur plusieurs lignes.

L’exemple suivant illustre la définition de la propriété LineHeight pour un Label :

<Label Text="Lorem ipsum dolor sit amet, consectetur adipiscing elit. In facilisis nulla eu felis fringilla vulputate. Nullam porta eleifend lacinia. Donec at iaculis tellus."
       LineBreakMode="WordWrap"
       LineHeight="1.8" />

La capture d’écran suivante montre le résultat de la définition de la propriété Label.LineHeight sur 1.8 :

Capture d’écran d’un exemple de hauteur de ligne de Label.

Afficher le code HTML

Important

L’affichage du HTML dans un Label est limité aux balises HTML prises en charge par la plateforme sous-jacente. Par exemple, Android prend seulement en charge un sous-ensemble de balises HTML, se limitant à l’application de styles et à la mise en forme de base pour les éléments de niveau bloc tels que <span> et <p>. Pour un rendu HTML plus complexe, envisagez d’utiliser un WebView ou FormattedText.

La classe Label dispose d’une propriété TextType, qui détermine si l’objet Label doit afficher du texte brut ou du texte HTML. Cette propriété doit être définie comme étant l’un des membres de l’énumération TextType :

  • Text indique que le Label affiche du texte brut ; il s’agit de la valeur par défaut de la propriété TextType.
  • Html indique que le Label affiche du texte HTML.

Par conséquent, les objets Label peuvent afficher du HTML en définissant la propriété TextType sur Html, et la propriété Text sur une chaîne HTML :

Label label = new Label
{
    Text = "This is <span style=\"color:red;\"><strong>HTML</strong></span> text.",
    TextType = TextType.Html
};

Dans l’exemple ci-dessus, les caractères de guillemets doubles figurant dans le HTML doivent être placés dans une séquence d’échappement avec le symbole \.

En XAML, les chaînes HTML peuvent devenir illisibles en raison de l’échappement supplémentaire des symboles < et > :

<Label Text="This is &lt;span style=&quot;color:red&quot;&gt;&lt;strong&gt;HTML&lt;/strong&gt;&lt;/span&gt; text."
       TextType="Html"  />

Sinon, pour une meilleure lisibilité, le HTML peut être inclus dans une section CDATA :

<Label TextType="Html">
    <![CDATA[
    <Label Text="This is &lt;span style=&quot;color:red&quot;&gt;&lt;strong&gt;HTML&lt;/strong&gt;&lt;/span&gt; text."
    ]]>
</Label>

Dans cet exemple, la propriété Text est définie sur la chaîne HTML incluse dans la section CDATA. Cela fonctionne, car la propriété Text est la ContentProperty de la classe Label.

Décorer du texte

Les décorations de texte souligné et barré peuvent être appliquées aux objets Label en définissant la propriété TextDecorations sur un ou plusieurs membres de l’énumération TextDecorations :

  • None
  • Underline
  • Strikethrough

L’exemple suivant illustre la définition de la propriété TextDecorations :

<Label Text="This is underlined text." TextDecorations="Underline"  />
<Label Text="This is text with strikethrough." TextDecorations="Strikethrough" />
<Label Text="This is underlined text with strikethrough." TextDecorations="Underline, Strikethrough" />

Le code C# équivalent est :

Label underlineLabel = new Label { Text = "This is underlined text.", TextDecorations = TextDecorations.Underline };
Label strikethroughLabel = new Label { Text = "This is text with strikethrough.", TextDecorations = TextDecorations.Strikethrough };
Label bothLabel = new Label { Text = "This is underlined text with strikethrough.", TextDecorations = TextDecorations.Underline | TextDecorations.Strikethrough };

La capture d’écran suivante montre les membres de l’énumération TextDecorations appliqués aux instances Label :

Capture d’écran d’instances Label avec des décorations de texte.

Remarque

Des décorations de texte peuvent également être appliquées aux instances Span. Pour plus d’informations sur la classe Span, consultez Utiliser du texte mis en forme.

Transformer le texte

Un Label peut transformer la casse de son texte, stocké dans la propriété Text, en attribuant à la propriété TextTransform une valeur de l’énumération TextTransform. Cette énumération compte 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 :

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

Utiliser du texte mis en forme

Label expose une propriété FormattedText qui permet de présenter du texte avec plusieurs polices et couleurs dans une même vue. La propriété FormattedText est de type FormattedString, qui comprend une ou plusieurs instances Span, définies via la propriété Spans.

Remarque

Il n’est pas possible d’afficher du HTML dans un Span.

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

  • BackgroundColor, de type Color, qui représente la couleur d’arrière-plan de l’objet Span.
  • CharacterSpacing, de type double, définit l’espacement entre les caractères dans le texte affiché.
  • FontAttributes, de type FontAttributes, détermine le style du 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.
  • LineHeight, de type double, spécifie le multiplicateur à appliquer à la hauteur de ligne par défaut lors de l’affichage du texte.
  • Style, de type Style, qui est le style à appliquer à l’objet Span.
  • Text, de type string, définit le texte affiché comme contenu du Span.
  • TextColor, de type Color, définit la couleur du texte affiché.
  • TextDecorations, de type TextDecorations, spécifie les décorations de texte (souligné et barré) qui peuvent être appliquées.
  • TextTransform, de type TextTransform, spécifie la casse du texte affiché.

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.

Remarque

La propriété Span.LineHeight n’a aucun effet sur Windows.

De plus, la propriété GestureRecognizers peut être utilisée pour définir une collection de modules de reconnaissance de mouvement qui répondront aux mouvements au niveau du Span.

L’exemple XAML suivant illustre une propriété FormattedText composée de trois instances Span :

<Label LineBreakMode="WordWrap">
    <Label.FormattedText>
        <FormattedString>
            <Span Text="Red Bold, " TextColor="Red" FontAttributes="Bold" />
            <Span Text="default, " FontSize="14">
                <Span.GestureRecognizers>
                    <TapGestureRecognizer Command="{Binding TapCommand}" />
                </Span.GestureRecognizers>
            </Span>
            <Span Text="italic small." FontAttributes="Italic" FontSize="12" />
        </FormattedString>
    </Label.FormattedText>
</Label>

Le code C# équivalent est :

FormattedString formattedString = new FormattedString ();
formattedString.Spans.Add (new Span { Text = "Red bold, ", TextColor = Colors.Red, FontAttributes = FontAttributes.Bold });

Span span = new Span { Text = "default, " };
span.GestureRecognizers.Add(new TapGestureRecognizer { Command = new Command(async () => await DisplayAlert("Tapped", "This is a tapped Span.", "OK")) });
formattedString.Spans.Add(span);
formattedString.Spans.Add (new Span { Text = "italic small.", FontAttributes = FontAttributes.Italic, FontSize = 14 });

Label label = new Label { FormattedText = formattedString };

La capture d’écran suivante montre le Label obtenu qui contient trois objets Span :

Capture d’écran d’un objet Label composé de trois instances Span.

Un Span peut également répondre aux mouvements ajoutés à la collection GestureRecognizers de l’objet Span. Par exemple, un TapGestureRecognizer a été ajouté à la deuxième instance Span dans les exemples ci-dessus. Par conséquent, lorsque l’utilisateur appuie sur ce Span, le TapGestureRecognizer répond en exécutant l’ICommand définie par la propriété Command. Pour plus d’informations sur la reconnaissance des mouvements d’appui, consultez Reconnaître un mouvement d’appui.

Le texte affiché par les instances Label et Span peut être transformé en liens hypertexte sur lesquels l’utilisateur peut appuyer à l’aide de l’approche suivante :

  1. Définissez les propriétés TextColor et TextDecoration de l’instance Label ou Span.
  2. Ajoutez un TapGestureRecognizer à la collection GestureRecognizers de l’instance Label ou Span, dont la propriété Command est liée à une ICommand, et dont la propriété CommandParameter contient l’URL à ouvrir.
  3. Définissez l’ICommand qui sera exécutée par le TapGestureRecognizer.
  4. Écrivez le code qui sera exécuté par l’ICommand.

L’exemple suivant montre un Label dont le contenu est défini à partir de plusieurs objets Span :

<Label>
    <Label.FormattedText>
        <FormattedString>
            <Span Text="Alternatively, click " />
            <Span Text="here"
                  TextColor="Blue"
                  TextDecorations="Underline">
                <Span.GestureRecognizers>
                    <TapGestureRecognizer Command="{Binding TapCommand}"
                                          CommandParameter="https://learn.microsoft.com/dotnet/maui/" />
                </Span.GestureRecognizers>
            </Span>
            <Span Text=" to view .NET MAUI documentation." />
        </FormattedString>
    </Label.FormattedText>
</Label>

Dans cet exemple, les première et troisième instances Span contiennent du texte, alors que la deuxième instance Span représente un lien hypertexte sur lequel l’utilisateur peut appuyer. La couleur de texte définie pour cette dernière est le bleu, et elle présente une décoration de texte souligné. Cela lui donne l’aspect d’un lien hypertexte, comme le montre la capture d’écran suivante :

Capture d’écran d’un lien hypertexte.

Lorsque l’utilisateur appuie sur le lien hypertexte, le TapGestureRecognizer répond en exécutant l’ICommand définie par sa propriété Command. Par ailleurs, l’URL spécifiée par la propriété CommandParameter est transmise à l’ICommand en tant que paramètre.

Le code-behind de la page XAML contient l’implémentation de TapCommand :

using System.Windows.Input;

public partial class MainPage : ContentPage
{
    // Launcher.OpenAsync is provided by Essentials.
    public ICommand TapCommand => new Command<string>(async (url) => await Launcher.OpenAsync(url));

    public MainPage()
    {
        InitializeComponent();
        BindingContext = this;
    }
}

TapCommand exécute la méthode Launcher.OpenAsync, transmettant la valeur de la propriété TapGestureRecognizer.CommandParameter en tant que paramètre. La méthode Launcher.OpenAsync ouvre l’URL dans un navigateur web. Par conséquent, l’effet global est que lorsque l’utilisateur appuie sur le lien hypertexte dans la page, une fenêtre de navigateur web s’affiche et accède à l’URL associée au lien hypertexte.

L’approche utilisée précédemment pour créer un lien hypertexte vous impose d’écrire du code répétitif chaque fois que vous avez besoin d’un lien hypertexte dans votre application. Toutefois, les classes Label et Span peuvent être sous-classées pour créer des classes HyperlinkLabel et HyperlinkSpan, dans lesquelles sont ajoutés le module de reconnaissance de mouvement et le code de mise en forme.

L’exemple suivant présente une classe HyperlinkSpan :

public class HyperlinkSpan : Span
{
    public static readonly BindableProperty UrlProperty =
        BindableProperty.Create(nameof(Url), typeof(string), typeof(HyperlinkSpan), null);

    public string Url
    {
        get { return (string)GetValue(UrlProperty); }
        set { SetValue(UrlProperty, value); }
    }

    public HyperlinkSpan()
    {
        TextDecorations = TextDecorations.Underline;
        TextColor = Colors.Blue;
        GestureRecognizers.Add(new TapGestureRecognizer
        {
            // Launcher.OpenAsync is provided by Essentials.
            Command = new Command(async () => await Launcher.OpenAsync(Url))
        });
    }
}

La classe HyperlinkSpan définit une propriété Url, ainsi que la BindableProperty associée, et le constructeur définit l’apparence du lien hypertexte et le TapGestureRecognizer qui répond lorsqu’un utilisateur appuie sur le lien hypertexte. Lorsqu’un utilisateur appuie sur un HyperlinkSpan, le TapGestureRecognizer répond en exécutant la méthode Launcher.OpenAsync pour ouvrir l’URL, spécifiée par la propriété Url, dans une fenêtre de navigateur web.

La classe HyperlinkSpan peut être consommée en ajoutant une instance de la classe au code XAML :

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:local="clr-namespace:HyperlinkDemo"
             x:Class="HyperlinkDemo.MainPage">
    <StackLayout>
        ...
        <Label>
            <Label.FormattedText>
                <FormattedString>
                    <Span Text="Alternatively, click " />
                    <local:HyperlinkSpan Text="here"
                                         Url="https://learn.microsoft.com/dotnet/" />
                    <Span Text=" to view .NET documentation." />
                </FormattedString>
            </Label.FormattedText>
        </Label>
    </StackLayout>
</ContentPage>