Xamarin.Forms Etiqueta

  • Artigo

Download Sample Baixe o exemplo

Exibir texto em Xamarin.Forms

O Label modo de exibição é usado para exibir texto, tanto de linha única quanto de várias linhas. Os rótulos podem ter decorações de texto, texto colorido e usar fontes personalizadas (famílias, tamanhos e opções).

Decorações de texto

As decorações de texto de sublinhado e tachado podem ser aplicadas a instâncias definindo a LabelLabel.TextDecorations propriedade como um ou mais TextDecorations membros de enumeração:

  • None
  • Underline
  • Strikethrough

O exemplo XAML a seguir demonstra a configuração da Label.TextDecorations propriedade:

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

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

As capturas de tela a seguir mostram os membros de TextDecorations enumeração aplicados às Label instâncias:

Labels with Text Decorations

Observação

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

Texto de transformação

A Label pode transformar o invólucro de seu texto, armazenado na Text propriedade, definindo a TextTransform propriedade como um valor da TextTransform enumeração. Essa enumeração tem quatro valores:

  • None indica que o texto não será transformado.
  • Default indica que o comportamento padrão para a 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úsculas.

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

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

Este é o código C# equivalente:

Label label = new Label
{
    Text = "This text will be displayed in uppercase.",
    TextTransform = TextTransform.Uppercase
};

Espaçamento de caracteres

O espaçamento entre caracteres pode ser aplicado a instâncias definindo a LabelLabel.CharacterSpacing propriedade como um double valor:

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

Este é o código C# equivalente:

Label label = new Label { Text = "Character spaced text", CharacterSpacing = 10 };

O resultado é que os caracteres no texto exibido pelo são espaçados CharacterSpacing entre unidades independentes de Label dispositivo.

Novas linhas

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

  1. Use o caractere de alimentação de linha unicode, que é " ".
  2. Especifique seu 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>

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

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

Cores

Os rótulos podem ser definidos para usar uma cor de texto personalizada por meio da propriedade vinculável TextColor .

É necessário um cuidado especial para garantir que as cores sejam utilizáveis em cada plataforma. Como cada plataforma tem padrões diferentes para cores de texto e plano de fundo, você precisará ter cuidado para escolher um padrão que funcione em cada uma.

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

<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="TextSample.LabelPage"
             Title="Label Demo">
    <StackLayout Padding="5,10">
      <Label TextColor="#77d065" FontSize = "20" Text="This is a green label." />
    </StackLayout>
</ContentPage>

Este é o código C# equivalente:

public partial class LabelPage : ContentPage
{
    public LabelPage ()
    {
        InitializeComponent ();

        var layout = new StackLayout { Padding = new Thickness(5,10) };
        var label = new Label { Text="This is a green label.", TextColor = Color.FromHex("#77d065"), FontSize = 20 };
        layout.Children.Add(label);
        this.Content = layout;
    }
}

As capturas de tela a seguir mostram o resultado da configuração da TextColor propriedade:

Label TextColor Example

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

Fontes

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

Truncamento e empacotamento

Os rótulos podem ser definidos para manipular texto que não cabe em uma linha de uma das várias maneiras, expostas pela LineBreakMode propriedade. LineBreakMode é uma enumeração com os seguintes valores:

  • HeadTruncation – trunca o cabeçalho do texto, mostrando o final.
  • CharacterWrap – quebra o texto em uma nova linha em um limite de caracteres.
  • MiddleTruncation – exibe o início e o fim do texto, com o meio substituído por uma reticência.
  • NoWrap – não quebra texto, exibindo apenas o máximo de texto que pode caber em uma linha.
  • TailTruncation – mostra o início do texto, truncando o final.
  • WordWrap – quebra o texto no limite da palavra.

Exibir um número específico de linhas

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

  • Quando MaxLines é -1, que é seu valor padrão, o respeita o valor da LineBreakMode propriedade para mostrar apenas uma linha, possivelmente truncada, ou todas as linhas com todo o Label texto.
  • Quando MaxLines é 0, o Label não é exibido.
  • Quando MaxLines é 1, o resultado é idêntico à definição da LineBreakMode propriedade como NoWrap, , MiddleTruncationHeadTruncationou TailTruncation. No entanto, o valor do LineBreakMode imóvel será respeitado no que diz respeito à colocação de uma reticência, se for o Label caso.
  • Quando MaxLines for maior que 1, o será exibido até o número especificado de linhas, respeitando o Label valor da LineBreakMode propriedade em relação à colocação de reticências, se aplicável. No entanto, definir a propriedade como um valor maior que 1 não terá efeito se a MaxLinesLineBreakMode propriedade for definida como NoWrap.

O exemplo XAML a seguir demonstra a configuração da MaxLines propriedade 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" />

Este é o código C# equivalente:

var 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 = LineBreakMode.WordWrap,
  MaxLines = 2
};

As capturas de tela a seguir mostram o resultado da configuração MaxLines da propriedade como 2, quando o texto é longo o suficiente para ocupar mais de 2 linhas:

Label MaxLines Example

Exibir HTML

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

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

Portanto, as instâncias podem exibir HTML definindo a propriedade como , Label e a Label.TextLabel.TextType propriedade como Htmluma cadeia de caracteres HTML:

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

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

Em XAML, as cadeias de caracteres HTML podem se tornar ilegíveis devido à fuga adicional dos < símbolos e > :

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

Como alternativa, para maior legibilidade, o HTML pode ser embutido em uma CDATA seção:

<Label TextType="Html">
    <![CDATA[
    This is <strong style="color:red">HTML</strong> text.
    ]]>
</Label>

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

As capturas de tela a seguir mostram um Label HTML de exibição:

Screenshots of a Label displaying HTML, on iOS and Android

Importante

A exibição de HTML em um Label é limitada às marcas HTML que são suportadas pela plataforma subjacente.

Texto formatado

Os rótulos expõem uma FormattedText propriedade que permite a apresentação de texto com várias fontes e cores no mesmo modo de exibição.

A FormattedText propriedade é do tipo FormattedString, que compreende uma ou mais Span instâncias, definidas por meio da Spans propriedade. As seguintes Span propriedades podem ser usadas para definir a aparência visual:

  • BackgroundColor – a cor do fundo do vão.
  • CharacterSpacing, do tipo , é o espaçamento entre caracteres do doubleSpan texto.
  • Font – a fonte do texto no vão.
  • FontAttributes – os atributos de fonte para o texto no span.
  • FontFamily – a família de fontes à qual pertence a fonte do texto no intervalo.
  • FontSize – o tamanho da fonte para o texto no vão.
  • ForegroundColor – a cor do texto no vão. Esta propriedade está obsoleta e foi substituída TextColor pela propriedade.
  • LineHeight - o multiplicador a aplicar à altura da linha padrão do vão. Para obter mais informações, consulte Altura da linha.
  • Style – o estilo a ser aplicado ao vão.
  • Text – o texto do vão.
  • TextColor – a cor do texto no vão.
  • TextDecorations - as decorações a aplicar ao texto no vão. Para obter mais informações, consulte Decorações de texto.

As BackgroundColorpropriedades , Texte Text vinculável têm um modo de vinculação padrão de OneWay. Para obter mais informações sobre esse modo de vinculação, consulte O modo de vinculação padrão no guia Modo de vinculação.

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

Observação

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

O exemplo XAML a seguir demonstra uma FormattedText propriedade que consiste em três Span instâncias:

<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="TextSample.LabelPage"
             Title="Label Demo - XAML">
    <StackLayout Padding="5,10">
        ...
        <Label LineBreakMode="WordWrap">
            <Label.FormattedText>
                <FormattedString>
                    <Span Text="Red Bold, " TextColor="Red" FontAttributes="Bold" />
                    <Span Text="default, " Style="{DynamicResource BodyStyle}">
                        <Span.GestureRecognizers>
                            <TapGestureRecognizer Command="{Binding TapCommand}" />
                        </Span.GestureRecognizers>
                    </Span>
                    <Span Text="italic small." FontAttributes="Italic" FontSize="Small" />
                </FormattedString>
            </Label.FormattedText>
        </Label>
    </StackLayout>
</ContentPage>

Este é o código C# equivalente:

public class LabelPageCode : ContentPage
{
    public LabelPageCode ()
    {
        var layout = new StackLayout{ Padding = new Thickness (5, 10) };
        ...
        var formattedString = new FormattedString ();
        formattedString.Spans.Add (new Span{ Text = "Red bold, ", ForegroundColor = Color.Red, FontAttributes = FontAttributes.Bold });

        var 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 =  Device.GetNamedSize(NamedSize.Small, typeof(Label)) });

        layout.Children.Add (new Label { FormattedText = formattedString });
        this.Content = layout;
    }
}

Importante

A Text propriedade de um Span pode ser definida por meio de associação de dados. Para obter mais informações, confira Associação de dados.

Observe que um Span também pode responder a quaisquer gestos adicionados à coleção da GestureRecognizers extensão. Por exemplo, um TapGestureRecognizer foi adicionado ao segundo Span nos exemplos de código acima. Portanto, quando isso Span é tocado, o irá responder executando o ICommandTapGestureRecognizer definido pela Command propriedade. Para obter mais informações sobre reconhecedores de gestos, consulte Xamarin.Forms Gestos.

As capturas de tela a seguir mostram o resultado da configuração FormattedString da propriedade para três Span instâncias:

Label FormattedText Example

Altura da linha

A altura vertical de a e a pode ser personalizada definindo a LabelSpanLabel.LineHeight propriedade ou Span.LineHeight um double valor. No iOS e no Android, esses valores são multiplicadores da altura da linha original e, na Plataforma Universal do Windows (UWP), o Label.LineHeight valor da propriedade é um multiplicador do tamanho da fonte do rótulo.

Observação

O exemplo XAML a seguir demonstra a configuração da LineHeight propriedade 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" />

Este é o código C# equivalente:

var 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 = LineBreakMode.WordWrap,
  LineHeight = 1.8
};

As capturas de tela a seguir mostram o resultado da configuração da Label.LineHeight propriedade como 1.8:

Label LineHeight Example

O exemplo XAML a seguir demonstra a configuração da LineHeight propriedade em um Span:

<Label LineBreakMode="WordWrap">
    <Label.FormattedText>
        <FormattedString>
            <Span Text="Lorem ipsum dolor sit amet, consectetur adipiscing elit. In a tincidunt sem. Phasellus mollis sit amet turpis in rutrum. Sed aliquam ac urna id scelerisque. "
                  LineHeight="1.8"/>
            <Span Text="Nullam feugiat sodales elit, et maximus nibh vulputate id."
                  LineHeight="1.8" />
        </FormattedString>
    </Label.FormattedText>
</Label>

Este é o código C# equivalente:

var formattedString = new FormattedString();
formattedString.Spans.Add(new Span
{
  Text = "Lorem ipsum dolor sit amet, consectetur adipiscing elit. In a tincidunt sem. Phasellus mollis sit amet turpis in rutrum. Sed aliquam ac urna id scelerisque. ",
  LineHeight = 1.8
});
formattedString.Spans.Add(new Span
{
  Text = "Nullam feugiat sodales elit, et maximus nibh vulputate id.",
  LineHeight = 1.8
});
var label = new Label
{
  FormattedText = formattedString,
  LineBreakMode = LineBreakMode.WordWrap
};

As capturas de tela a seguir mostram o resultado da configuração da Span.LineHeight propriedade como 1.8:

Span LineHeight Example

Preenchimento

O preenchimento representa o espaço entre um elemento e seus elementos filho e é usado para separar o elemento de seu próprio conteúdo. O preenchimento pode ser aplicado a instâncias definindo a LabelLabel.Padding propriedade como um Thickness valor:

<Label Padding="10">
    <Label.FormattedText>
        <FormattedString>
            <Span Text="Lorem ipsum" />
            <Span Text="dolor sit amet." />
        </FormattedString>
    </Label.FormattedText>
</Label>

Este é o código C# equivalente:

FormattedString formattedString = new FormattedString();
formattedString.Spans.Add(new Span
{
  Text = "Lorem ipsum"
});
formattedString.Spans.Add(new Span
{
  Text = "dolor sit amet."
});
Label label = new Label
{
    FormattedText = formattedString,
    Padding = new Thickness(20)
};

Importante

No iOS, quando for criado um Label que defina a propriedade, o Padding preenchimento será aplicado e o valor de preenchimento poderá ser atualizado posteriormente. No entanto, quando um Label é criado que não define a Padding propriedade, tentar defini-lo mais tarde não terá efeito.

No Android e na Plataforma Universal do Windows, o valor da propriedade pode ser especificado quando o PaddingLabel é criado ou posterior.

Para obter mais informações sobre preenchimento, consulte Margens e preenchimento.

O texto exibido por Label e Span instâncias pode ser transformado em hiperlinks com a seguinte abordagem:

  1. Defina as TextColor propriedades e TextDecoration do Label ou Span.
  2. Adicione a à GestureRecognizers coleção do Label ou Span, cuja propriedade se vincula a um ICommand, e cuja CommandCommandParameter propriedade contém a URL a TapGestureRecognizer ser aberta.
  3. Defina o ICommand que será executado pelo TapGestureRecognizer.
  4. Escreva o código que será executado pelo ICommand.

O exemplo de código a seguir, retirado do exemplo de demonstrações de hiperlink , mostra um Label cujo conteúdo é definido de várias Span instâncias:

<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/xamarin/" />
                </Span.GestureRecognizers>
            </Span>
            <Span Text=" to view Xamarin documentation." />
        </FormattedString>
    </Label.FormattedText>
</Label>

Neste exemplo, a primeira e a terceira Span instâncias compreendem texto, enquanto a segunda Span representa um hiperlink tappable. 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 nas seguintes capturas de tela:

Hyperlinks

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

O code-behind para a página XAML contém a TapCommand implementação:

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

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

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

A abordagem anterior para criar um hiperlink requer escrever código repetitivo sempre que você precisar de um hiperlink em seu aplicativo. No entanto, as Label classes e podem ser subclassificadas para criar HyperlinkLabel e classes, com o reconhecedor de gestos e SpanHyperlinkSpan o código de formatação de texto adicionados lá.

O exemplo de código a seguir, retirado do exemplo de demonstrações de hiperlink , mostra uma HyperlinkSpan classe:

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 = Color.Blue;
        GestureRecognizers.Add(new TapGestureRecognizer
        {
            // Launcher.OpenAsync is provided by Xamarin.Essentials.
            Command = new Command(async () => await Launcher.OpenAsync(Url))
        });
    }
}

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

A HyperlinkSpan classe pode ser consumida adicionando uma instância da classe ao XAML:

<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
             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/appcenter/" />
                    <Span Text=" to view AppCenter documentation." />
                </FormattedString>
            </Label.FormattedText>
        </Label>
    </StackLayout>
</ContentPage>

Etiquetas de estilo

As seções anteriores abordaram a configuração Label e Span as propriedades por instância. No entanto, conjuntos de propriedades podem ser agrupados em um estilo que é consistentemente aplicado a um ou vários modos de exibição. Isso pode aumentar a legibilidade do código e tornar as alterações de design mais fáceis de implementar. Para obter mais informações, consulte Estilos.