Rótulo do xamarin. FormsXamarin.Forms Label

Baixar exemplo baixar o exemploDownload Sample Download the sample

Exibir o texto no xamarin. FormsDisplay text in Xamarin.Forms

O Label exibição é usada para exibir o texto, único e de várias linha.The Label view is used for displaying text, both single and multi-line. Rótulos podem ter as decorações de texto, texto colorido e usar fontes personalizadas (famílias, tamanhos e opções).Labels can have text decorations, colored text, and use custom fonts (families, sizes, and options).

Decorações de textoText decorations

Decorações de texto sublinhado e tachado podem ser aplicadas a Label instâncias, definindo o Label.TextDecorations propriedade a um ou mais TextDecorations membros de enumeração:Underline and strikethrough text decorations can be applied to Label instances by setting the Label.TextDecorations property to one or more TextDecorations enumeration members:

  • None
  • Underline
  • Strikethrough

O exemplo XAML a seguir demonstra a configuração de Label.TextDecorations propriedade:The following XAML example demonstrates setting the Label.TextDecorations property:

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

O código c# equivalente é:The equivalent C# code is:

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 TextDecorations aplicados a membros da enumeração Label instâncias:The following screenshots show the TextDecorations enumeration members applied to Label instances:

Rótulos com decorações de texto

Observação

Decorações de texto também podem ser aplicadas a Span instâncias.Text decorations can also be applied to Span instances. Para obter mais informações sobre o Span classe, consulte texto formatado em.For more information about the Span class, see Formatted Text.

CoresColors

Rótulos podem ser definidos para usar uma cor de texto personalizado por meio de associável TextColor propriedade.Labels can be set to use a custom text color via the bindable TextColor property.

Cuidado especial é necessário para garantir que as cores poderá ser usadas em cada plataforma.Special care is necessary to ensure that colors will be usable on each platform. Como cada plataforma tem diferentes padrões de cores de plano de fundo e texto, você precisará ter cuidado para escolher um padrão que funciona em cada um.Because each platform has different defaults for text and background colors, you'll need to be careful to pick a default that works on each.

O exemplo XAML a seguir define a cor do texto de um Label:The following XAML example sets the text color of a 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>

O código c# equivalente é:The equivalent C# code is:

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 de TextColor propriedade:The following screenshots show the result of setting the TextColor property:

Exemplo de TextColor de rótulo

Para obter mais informações sobre as cores, consulte cores.For more information about colors, see Colors.

FontesFonts

Para obter mais informações sobre como especificar fontes em uma Label, consulte fontes.For more information about specifying fonts on a Label, see Fonts.

Truncamento e quebra automáticaTruncation and wrapping

Rótulos podem ser definidos para lidar com o texto que não cabe em uma linha em uma das várias maneiras, expostas pelo LineBreakMode propriedade.Labels can be set to handle text that can't fit on one line in one of several ways, exposed by the LineBreakMode property. LineBreakMode é uma enumeração com os seguintes valores:LineBreakMode is an enumeration with the following values:

  • HeadTruncation – trunca o cabeçalho do texto, mostrando o final.HeadTruncation – truncates the head of the text, showing the end.
  • CharacterWrap – quebra o texto em uma nova linha em um limite de caractere.CharacterWrap – wraps text onto a new line at a character boundary.
  • MiddleTruncation – exibe o início e fim do texto, com a substituição do meio por reticências.MiddleTruncation – displays the beginning and end of the text, with the middle replace by an ellipsis.
  • NoWrap – não quebra o texto, exibindo somente texto como pode cabe em uma linha.NoWrap – does not wrap text, displaying only as much text as can fit on one line.
  • TailTruncation – mostra o início do texto, truncando final.TailTruncation – shows the beginning of the text, truncating the end.
  • WordWrap – quebra o texto no limite de palavra.WordWrap – wraps text at the word boundary.

Exibindo um número específico de linhasDisplaying a specific number of lines

O número de linhas exibidas por um Label pode ser especificada definindo o Label.MaxLines propriedade para um int valor:The number of lines displayed by a Label can be specified by setting the Label.MaxLines property to a int value:

  • Quando MaxLines é 0, o Label respeita o valor da LineBreakMode propriedade como mostram apenas uma linha, possivelmente truncada, ou todas as linhas com todo o texto.When MaxLines is 0, the Label respects the value of the LineBreakMode property to either show just one line, possibly truncated, or all lines with all text.
  • Quando MaxLines for 1, o resultado é idêntico à configuração de LineBreakMode propriedade a ser NoWrap , HeadTruncation , MiddleTruncation , ou TailTruncation .When MaxLines is 1, the result is identical to setting the LineBreakMode property to NoWrap, HeadTruncation, MiddleTruncation, or TailTruncation. No entanto, o Label respeitará o valor da LineBreakMode propriedade em relação ao posicionamento de reticências, se aplicável.However, the Label will respect the value of the LineBreakMode property with regard to placement of an ellipsis, if applicable.
  • Quando MaxLines é maior que 1, o Label exibirá até o número especificado de linhas, respeitando o valor da LineBreakMode propriedade em relação ao posicionamento de reticências, se aplicável.When MaxLines is greater than 1, the Label will display up to the specified number of lines, while respecting the value of the LineBreakMode property with regard to placement of an ellipsis, if applicable. No entanto, definir a MaxLines propriedade para um valor maior que 1 não tem nenhum efeito se o LineBreakMode estiver definida como NoWrap .However, setting the MaxLines property to a value greater than 1 has no effect if the LineBreakMode property is set to NoWrap.

O exemplo XAML a seguir demonstra a configuração de MaxLines propriedade em um Label :The following XAML example demonstrates setting the MaxLines property on a 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" />

O código c# equivalente é:The equivalent C# code is:

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 de MaxLines propriedade como 2, quando o texto é longo o suficiente para ocupar mais de 2 linhas:The following screenshots show the result of setting the MaxLines property to 2, when the text is long enough to occupy more than 2 lines:

Exemplo de MaxLines de rótulo

Texto formatadoFormatted text

Os rótulos expõem uma FormattedText propriedade que permite a apresentação do texto com várias fontes e cores na mesma exibição.Labels expose a FormattedText property that allows the presentation of text with multiple fonts and colors in the same view.

O FormattedText propriedade é do tipo FormattedString , que consiste em um ou mais Span instâncias, definidas por meio de Spans propriedade .The FormattedText property is of type FormattedString, which comprises one or more Span instances, set via the Spans property. O seguinte Span propriedades podem ser usadas para definir a aparência visual:The following Span properties can be used to set visual appearance:

  • BackgroundColor – a cor do plano de fundo span.BackgroundColor – the color of the span background.
  • Font – a fonte do texto no trecho.Font – the font for the text in the span.
  • FontAttributes – os atributos de fonte para o texto no trecho.FontAttributes – the font attributes for the text in the span.
  • FontFamily – a família de fontes ao qual pertence a fonte do texto no trecho.FontFamily – the font family to which the font for the text in the span belongs.
  • FontSize – o tamanho da fonte para o texto no trecho.FontSize – the size of the font for the text in the span.
  • ForegroundColor – a cor do texto no trecho.ForegroundColor – the color for the text in the span. Essa propriedade está obsoleta e foi substituída pelo TextColor propriedade.This property is obsolete and has been replaced by the TextColor property.
  • LineHeight -o multiplicador para aplicar a altura de linha padrão da extensão.LineHeight - the multiplier to apply to the default line height of the span. Para obter mais informações, consulte altura da linha.For more information, see Line Height.
  • Style– o estilo a ser aplicado ao SPAN.Style – the style to apply to the span.
  • Text – o texto da marca span.Text – the text of the span.
  • TextColor – a cor do texto no trecho.TextColor – the color for the text in the span.
  • TextDecorations -as decorações para aplicar ao texto no trecho.TextDecorations - the decorations to apply to the text in the span. Para obter mais informações, consulte decorações de texto.For more information, see Text Decorations.

Observação

As BackgroundColorpropriedades Text, OneWaye Text vinculáveis têm um modo de associação padrão de.The BackgroundColor, Text, and Text bindable properties have a default binding mode of OneWay. Para obter mais informações sobre esse modo de ligação, consulte o modo de associação padrão no guia de modo de ligação .For more information about this binding mode, see The Default Binding Mode in the Binding Mode guide.

Além disso, o GestureRecognizers propriedade pode ser usada para definir uma coleção dos reconhecedores de gestos que irá responder a gestos no Span .In addition, the GestureRecognizers property can be used to define a collection of gesture recognizers that will respond to gestures on the Span.

O exemplo XAML a seguir demonstra uma FormattedText propriedade consiste em três Span instâncias:The following XAML example demonstrates a FormattedText property that consists of three Span instances:

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

O código c# equivalente é:The equivalent C# code is:

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

O Text propriedade de um Span pode ser definido por meio da vinculação de dados.The Text property of a Span can be set through data binding. Para obter mais informações, consulte associação de dados.For more information, see Data Binding.

Observe que um Span também pode responder a qualquer gestos que são adicionados para o período GestureRecognizers coleção.Note that a Span can also respond to any gestures that are added to the span's GestureRecognizers collection. Por exemplo, uma TapGestureRecognizer foi adicionada à segunda Span nos exemplos de código acima.For example, a TapGestureRecognizer has been added to the second Span in the above code examples. Portanto, quando isso Span é tocado a TapGestureRecognizer responderá executando o ICommand definido pelo Command propriedade.Therefore, when this Span is tapped the TapGestureRecognizer will respond by executing the ICommand defined by the Command property. Para obter mais informações sobre os reconhecedores de gestos, consulte xamarin. Forms gestos.For more information about gesture recognizers, see Xamarin.Forms Gestures.

As capturas de tela a seguir mostram o resultado da configuração de FormattedString propriedade para três Span instâncias:The following screenshots show the result of setting the FormattedString property to three Span instances:

Exemplo de FormattedText de rótulo

Altura da linhaLine height

A altura vertical de um Label e uma Span pode ser personalizado definindo o Label.LineHeight propriedade ou Span.LineHeight para um double valor.The vertical height of a Label and a Span can be customized by setting the Label.LineHeight property or Span.LineHeight to a double value. No iOS e Android, esses valores são multiplicadores da altura da linha original e na plataforma Universal de Windows (UWP) o Label.LineHeight valor da propriedade é um multiplicador de tamanho da fonte do rótulo.On iOS and Android these values are multipliers of the original line height, and on the Universal Windows Platform (UWP) the Label.LineHeight property value is a multiplier of the label font size.

Observação

O exemplo XAML a seguir demonstra a configuração de LineHeight propriedade em uma Label :The following XAML example demonstrates setting the LineHeight property on a 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" />

O código c# equivalente é:The equivalent C# code is:

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 de Label.LineHeight propriedade para o 1.8:The following screenshots show the result of setting the Label.LineHeight property to 1.8:

Exemplo de LineHeight de rótulo

O exemplo XAML a seguir demonstra a configuração de LineHeight propriedade em uma Span :The following XAML example demonstrates setting the LineHeight property on a 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>

O código c# equivalente é:The equivalent C# code is:

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 de Span.LineHeight propriedade para o 1.8:The following screenshots show the result of setting the Span.LineHeight property to 1.8:

Exemplo de span LineHeight

O texto exibido por Label e Span as instâncias podem ser transformados em hiperlinks com a seguinte abordagem:The text displayed by Label and Span instances can be turned into hyperlinks with the following approach:

  1. Defina as TextColor propriedades TextDecoration e do Label ou. SpanSet the TextColor and TextDecoration properties of the Label or Span.
  2. Adicione um TapGestureRecognizer Label ICommandà coleção de ou Span, CommandParameter cuja Command propriedade é vinculada a um e cuja propriedade contém a URL a ser aberta. GestureRecognizersAdd a TapGestureRecognizer to the GestureRecognizers collection of the Label or Span, whose Command property binds to a ICommand, and whose CommandParameter property contains the URL to open.
  3. Defina o ICommand que será executado TapGestureRecognizerpelo.Define the ICommand that will be executed by the TapGestureRecognizer.
  4. Escreva o código que será executado pelo ICommand.Write the code that will be executed by the ICommand.

O exemplo de código a seguir, extraído do exemplo de demonstrações de hiperlink , mostra um Label cujo conteúdo está definido de várias Span instâncias:The following code example, taken from the Hyperlink Demos sample, shows a Label whose content is set from multiple Span instances:

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

Neste exemplo, a primeira e terceira Span instâncias compõem texto, enquanto o segundo Span representa um hiperlink tappable.In this example, the first and third Span instances comprise text, while the second Span represents a tappable hyperlink. Ele tem sua cor de texto definida como azul e tem uma decoração de texto sublinhado.It has its text color set to blue, and has an underline text decoration. Isso cria a aparência de um hiperlink, conforme mostrado nas seguintes capturas de tela:This creates the appearance of a hyperlink, as shown in the following screenshots:

HiperlinksHyperlinks

Quando o hiperlink for tocado, o TapGestureRecognizer responderá executando o ICommand definido por sua Command propriedade.When the hyperlink is tapped, the TapGestureRecognizer will respond by executing the ICommand defined by its Command property. Além disso, a URL especificada pela CommandParameter propriedade será passada para o ICommand como um parâmetro.In addition, the URL specified by the CommandParameter property will be passed to the ICommand as a parameter.

O code-behind da página XAML contém a TapCommand implementação:The code-behind for the XAML page contains the TapCommand implementation:

public partial class MainPage : ContentPage
{
    public ICommand TapCommand => new Command<string>(OpenBrowser);

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

    void OpenBrowser(string url)
    {
        Device.OpenUri(new Uri(url));
    }
}

O TapCommand executa o OpenBrowser método, passando o valor TapGestureRecognizer.CommandParameter da propriedade como um parâmetro.The TapCommand executes the OpenBrowser method, passing the TapGestureRecognizer.CommandParameter property value as a parameter. Por sua vez, esse método chama Device.OpenUri o método para abrir a URL em um navegador da Web.In turn, this method calls the Device.OpenUri method to open the URL in a web browser. Portanto, o efeito geral é que, quando o hiperlink é tocado na página, um navegador da Web é exibido e a URL associada ao hiperlink é navegada para.Therefore, the overall effect is that when the hyperlink is tapped on the page, a web browser appears and the URL associated with the hyperlink is navigated to.

A abordagem anterior para criar um hiperlink requer escrever código repetitivo toda vez que você precisar de um hiperlink em seu aplicativo.The previous approach to creating a hyperlink requires writing repetitive code every time you require a hyperlink in your application. No entanto, Label as Span classes e podem ser subclasses para HyperlinkLabel criar HyperlinkSpan classes e, com o reconhecedor de gestos e o código de formatação de texto adicionado lá.However, both the Label and Span classes can be subclassed to create HyperlinkLabel and HyperlinkSpan classes, with the gesture recognizer and text formatting code added there.

O exemplo de código a seguir, extraído do exemplo de demonstrações de hiperlink , mostra uma HyperlinkSpan classe:The following code example, taken from the Hyperlink Demos sample, shows a HyperlinkSpan class:

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
        {
            Command = new Command(() => Device.OpenUri(new Uri(Url)))
        });
    }
}

A HyperlinkSpan classe define uma Url Propriedade e associada BindableProperty, e o construtor define a aparência do hiperlink e o TapGestureRecognizer que responderá quando o hiperlink for tocado.The HyperlinkSpan class defines a Url property, and associated BindableProperty, and the constructor sets the hyperlink appearance and the TapGestureRecognizer that will respond when the hyperlink is tapped. Quando um HyperlinkSpan for tocado, o TapGestureRecognizer responderá executando o Device.OpenUri método Url para abrir a URL, especificada pela propriedade, em um navegador da Web.When a HyperlinkSpan is tapped, the TapGestureRecognizer will respond by executing the Device.OpenUri method to open the URL, specified by the Url property, in a web browser.

A HyperlinkSpan classe pode ser consumida adicionando uma instância da classe ao XAML:The HyperlinkSpan class can be consumed by adding an instance of the class to the 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://docs.microsoft.com/appcenter/" />
                    <Span Text=" to view AppCenter documentation." />
                </FormattedString>
            </Label.FormattedText>
        </Label>
    </StackLayout>
</ContentPage>

Estilo de rótulosStyling labels

As seções anteriores coberto configuração Label e Span propriedades em uma base por instância.The previous sections covered setting Label and Span properties on a per-instance basis. No entanto, os conjuntos de propriedades podem ser agrupados em um estilo que é aplicado consistentemente a um ou vários modos de exibição.However, sets of properties can be grouped into one style that is consistently applied to one or many views. Isso pode aumentar a legibilidade do código e fazer alterações de design mais fácil de implementar.This can increase readability of code and make design changes easier to implement. Para obter mais informações, consulte estilos.For more information, see Styles.