Compartilhar via

Etiqueta

  • Artigo

Procurar amostra. Procurar no exemplo

A interface do usuário de aplicativo multiplataforma do .NET (.NET MAUI) Label exibe texto de linha única e de várias linhas. O texto exibido por um Label pode ser colorido, espaçado e pode ter decorações de texto.

Label define as propriedades a seguir:

  • CharacterSpacing, do tipo double, define o espaçamento entre os caracteres no texto exibido.
  • FontAttributes, do tipo FontAttributes, determina o estilo de texto.
  • FontAutoScalingEnabled, do tipo bool, define se o texto refletirá as preferências de escala definidas no sistema operacional. O valor padrão dessa propriedade é true.
  • FontFamily, do tipo string, define a família da fonte.
  • FontSize, do tipo double, define o tamanho da fonte.
  • FormattedText, do tipo FormattedString, especifica a apresentação de texto com várias opções de apresentação, como fontes e cores.
  • HorizontalTextAlignment, do tipo TextAlignment, define o alinhamento horizontal do texto exibido.
  • LineBreakMode, do tipo LineBreakMode, determina como o texto deve ser tratado quando não pode caber em uma linha.
  • LineHeight, do tipo double, especifica o multiplicador a ser aplicado à altura da linha padrão ao exibir texto.
  • MaxLines, do tipo int, indica o número máximo de linhas permitidas no Label.
  • Padding, do tipo Thickness, determina o preenchimento do rótulo.
  • Text, do tipo string, define o texto exibido como o conteúdo do rótulo.
  • TextColor, do tipo Color, define a cor do texto exibido.
  • TextDecorations, do tipo TextDecorations, especifica as decorações de texto (sublinhado e tachado) que podem ser aplicadas.
  • TextTransform, do tipo TextTransform, especifica a maiúscula do texto exibido.
  • TextType, do tipo TextType, determina se o Label texto sem formatação deve ser exibido ou texto HTML.
  • VerticalTextAlignment, do tipo TextAlignment, define o alinhamento vertical do texto exibido.

Essas propriedades são apoiadas por objetos BindableProperty, o que significa que podem ser alvos de associações de dados e ser estilizada.

Para obter informações sobre como especificar fontes em um Label, consulte Fontes.

Criar um rótulo

O exemplo a seguir mostra como criar um Label:

<Label Text="Hello world" />

Este é o código C# equivalente:

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

Definir cores

Os rótulos podem ser definidos para usar uma cor de texto específica por meio da propriedade TextColor.

O exemplo a seguir define a cor do texto de um Label:

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

Para obter mais informações sobre cores, consulte Cores.

Definir o espaçamento entre caracteres

O espaçamento de caracteres pode ser aplicado a objetos Label definindo a propriedade CharacterSpacing como um valor double:

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

O resultado é que os caracteres no texto exibido pelo Label são unidades CharacterSpacing separadas e espeçadas independentes do dispositivo.

Adicionar novas linhas

Há duas técnicas principais para forçar o texto em uma Label em uma nova linha, a partir do XAML:

  1. Use o caractere de feed de linha unicode, que é " ".
  2. Especifique o texto usando a sintaxe do elemento de propriedade.

O código a seguir mostra um exemplo de ambas as técnicas:

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

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

Em C#, o texto pode ser forçado em uma nova linha com o caractere "\n":

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

Controlar truncamento e encapsulamento de texto

O encapsulamento e o truncamento de texto podem ser controlados definindo a propriedade LineBreakMode como um valor da enumeração LineBreakMode:

  • NoWrap — não encapsula texto, exibindo apenas o máximo de texto que pode caber em uma linha. Este é o valor padrão da propriedade LineBreakMode.
  • WordWrap — encapsula o texto no limite da palavra.
  • CharacterWrap — encapsula o texto em uma nova linha em um limite de caractere.
  • HeadTruncation — trunca a cabeça do texto, mostrando o final.
  • MiddleTruncation — exibe o início e o final do texto, com a substituição intermediária por reticências.
  • TailTruncation — mostra o início do texto, truncando o final.

Exibir um número específico de linhas

O número de linhas exibidas por um Label pode ser especificado definindo a propriedade MaxLines como um valor int:

  • Quando MaxLines for -1, que é seu valor padrão, o Label respeita o valor da propriedade LineBreakMode para mostrar apenas uma linha, possivelmente truncada ou todas as linhas com todo o texto.
  • Quando MaxLines for 0, o Label não é exibido.
  • Quando MaxLines for 1, o resultado é idêntico à configuração da propriedade LineBreakMode como NoWrap, HeadTruncation, MiddleTruncation ou TailTruncation. No entanto, o Label irá respeita o valor da propriedade LineBreakMode em relação ao posicionamento de reticências, se aplicável.
  • Quando MaxLines for maior que 1, o Label irá exibir até o número especificado de linhas, respeitando o valor da propriedade LineBreakMode em relação ao posicionamento de reticências, se aplicável. No entanto, definir a propriedade MaxLines como um valor maior que 1 não terá efeito se a propriedade LineBreakMode estiver definida como NoWrap.

O exemplo XAML a seguir demonstra como definir a propriedade MaxLines em um 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" />

Definir altura da linha

A altura vertical de um Label pode ser personalizada definindo a propriedade Label.LineHeight como um valor double.

Observação

  • No iOS, a propriedade Label.LineHeight altera a altura da linha do texto que se encaixa em uma única linha e o texto que encapsula em várias linhas.
  • No Android, a propriedade Label.LineHeight altera apenas a altura da linha do texto que é encapsulada em várias linhas.
  • No Windows, a propriedade Label.LineHeight altera a altura da linha do texto que é encapsulada em várias linhas.

O exemplo a seguir demonstra como definir a propriedade LineHeight em um 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" />

A captura de tela a seguir mostra o resultado da configuração da propriedade Label.LineHeight como 1.8:

Captura de tela do exemplo de altura da linha Rótulos.

Exibir HTML

Importante

A exibição de HTML em um Label é limitada às marcas HTML compatíveis com a plataforma subjacente. Por exemplo, o Android dá suporte apenas a um subconjunto de marcas HTML, com foco no estilo básico e na formatação para elementos de nível de bloco, como <span> e <p>. Para uma renderização HTML mais complexa, considere usar um WebView ou FormattedText.

A classe Label tem uma propriedade TextType, que determina se o objeto Label deve exibir texto sem formatação ou texto HTML. Essa propriedade deve ser definida como um dos membros da enumeração TextType:

  • Text indica que o Label irá exibir texto sem formatação e é o valor padrão da propriedade TextType.
  • Html indica que o Label irá exibir texto HTML.

Portanto, os objetos Label podem exibir HTML definindo a propriedade TextType como Html, e a propriedade Text para uma cadeia de caracteres HTML:

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

No exemplo acima, os caracteres de aspas duplas no HTML precisam ser escapados usando o símbolo \.

No XAML, as cadeias de caracteres HTML podem se tornar ilegível devido ao escape adicional dos símbolos < e >:

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

Como alternativa, para maior legibilidade, o HTML pode ser embutido em uma seção 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>

Neste exemplo, a propriedade Text é definida como a cadeia de caracteres HTML que está embutida na seção CDATA. Isso funciona porque a propriedade Text é a ContentProperty da classe Label.

Decorar texto

As decorações de texto sublinhado e tachado podem ser aplicadas a objetos Label definindo a propriedade TextDecorations como um ou mais membros de enumeração TextDecorations:

  • None
  • Underline
  • Strikethrough

O exemplo a seguir demonstra como definir a propriedade 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" />

Este é o código C# equivalente:

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

A captura de tela a seguir mostra os membros de enumeração TextDecorations aplicados a instâncias Label:

Captura de tela de Rótulos com decorações de texto.

Observação

Decorações de texto também podem ser aplicadas a instâncias Span. Para obter mais informações sobre a classe Span, consulte Usar texto formatado.

Texto de transformação

Um Label pode transformar o uso de maiúsculas e minúsculas de seu texto, armazenada na propriedade Text, definindo a propriedade TextTransform como um valor da enumeraçãoTextTransform. Essa enumeração tem quatro valores:

  • None indica que o texto não será transformado.
  • Default indica que o comportamento padrão da plataforma será usado. Este é o valor padrão da propriedade TextTransform.
  • Lowercase indica que o texto será transformado em minúsculas.
  • Uppercase indica que o texto será transformado em maiúscula.

O exemplo a seguir mostra a transformação de texto em letras maiúsculas:

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

Usar texto formatado

Label expõe uma propriedade FormattedText que permite a apresentação de texto com várias fontes e cores na mesma exibição. A propriedade FormattedText é do tipo FormattedString, que compreende uma ou mais instâncias Span, definida por meio da propriedade Spans.

Observação

Não é possível exibir HTML em um Span.

Span define as propriedades a seguir:

  • BackgroundColor, do tipo Color, que representa a cor da tela de fundo do intervalo.
  • CharacterSpacing, do tipo double, define o espaçamento entre os caracteres no texto exibido.
  • FontAttributes, do tipo FontAttributes, determina o estilo de texto.
  • FontAutoScalingEnabled, do tipo bool, define se o texto refletirá as preferências de escala definidas no sistema operacional. O valor padrão dessa propriedade é true.
  • FontFamily, do tipo string, define a família da fonte.
  • FontSize, do tipo double, define o tamanho da fonte.
  • LineHeight, do tipo double, especifica o multiplicador a ser aplicado à altura da linha padrão ao exibir texto.
  • Style, do tipo Style, que é o estilo a ser aplicado ao intervalo.
  • Text, do tipo string, define o texto exibido como o conteúdo do Span.
  • TextColor, do tipo Color, define a cor do texto exibido.
  • TextDecorations, do tipo TextDecorations, especifica as decorações de texto (sublinhado e tachado) que podem ser aplicadas.
  • TextTransform, do tipo TextTransform, especifica a maiúscula do texto exibido.

Essas propriedades são apoiadas por objetos BindableProperty, o que significa que podem ser alvos de associações de dados e ser estilizada.

Observação

A propriedade Span.LineHeight não tem efeito no Windows.

Além disso, a propriedade GestureRecognizers pode ser usada para definir uma coleção de reconhecedores de gestos que responderão a gestos no Span.

O exemplo XAML a seguir demonstra uma propriedade FormattedText que consiste em três instâncias 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>

Este é o código C# equivalente:

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

A captura de tela a seguir mostra o resultado Label que contém três objetos Span:

Captura de tela do Rótulo que consiste em três intervalos.

Um Span também pode responder a qualquer gesto adicionado à coleção do intervalo GestureRecognizers. Por exemplo, um TapGestureRecognizer foi adicionado ao segundo Span nos exemplos acima. Portanto, quando esse Span for tocado, o TapGestureRecognizer irá responder executando o ICommand definido pela propriedade Command. Para obter mais informações sobre o reconhecimento de gestos de toque, consulte Reconhecer um gesto de toque.

O texto exibido pelas instâncias Label e Span instâncias podem ser transformados em hiperlinks com a seguinte abordagem:

  1. Definir as propriedades TextColor e TextDecoration do Label ou Span.
  2. Adicionar um TapGestureRecognizer à coleção GestureRecognizers do Label ou Span cuja propriedade Command se associa a um ICommand e cuja propriedade CommandParameter contém a URL a ser aberta.
  3. Definir o ICommand que será executado pelo TapGestureRecognizer.
  4. Escrever o código que será executado pelo ICommand.

O exemplo a seguir mostra um Label cujo conteúdo é definido de vários objetos 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>

Neste exemplo, a primeira e a terceira instâncias Span contêm texto, enquanto o segundo Span representa um hiperlink que pode ser tocado. Ele tem sua cor de texto definida como azul e tem uma decoração de texto sublinhado. Isso cria a aparência de um hiperlink, conforme mostrado na seguinte captura de tela:

Captura de tela de um hiperlink.

Quando o hiperlink for tocado, o TapGestureRecognizer irá responder executando o ICommand definido por sua propriedade Command. Além disso, a URL especificada pela propriedade CommandParameter será passada para o parâmetro ICommand como um parâmetro.

O code-behind da página XAML contém a implementação 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;
    }
}

O TapCommand executa o método Launcher.OpenAsync, passando o valor da propriedade TapGestureRecognizer.CommandParameter como um parâmetro. O método Launcher.OpenAsync abre a URL em um navegador da Web. Portanto, o efeito geral é que, quando o hiperlink é tocado na página, um navegador da Web é exibido e a URL associada ao hiperlink é navegada.

A abordagem anterior para criar um hiperlink requer a gravação de código repetitivo sempre que você precisar de um hiperlink em seu aplicativo. No entanto, as classes Label e Span podem ser divididas em subclasse para criar classes HyperlinkLabel e HyperlinkSpan, com o reconhecimento de gestos e o código de formatação de texto adicionados lá.

O exemplo a seguir mostra uma 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))
        });
    }
}

A classe HyperlinkSpan define uma Url propriedade e associada BindableProperty, e o construtor define a aparência do hiperlink e o TapGestureRecognizer que irá responde quando o hiperlink for tocado. Quando um HyperlinkSpan for tocado, o TapGestureRecognizer irá responder executando o método Launcher.OpenAsync para abrir a URL, especificada pela propriedade Url, em um navegador da Web.

A classe HyperlinkSpan pode ser consumida adicionando uma instância da classe ao 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>