Etiqueta

  • Artículo

Examinar ejemplo.Examinar el ejemplo

La interfaz de usuario de aplicación multiplataforma de .NET (.NET MAUI) Label muestra texto de una sola línea y de varias líneas. El texto mostrado por Label se puede colorear, espaciar y puede tener decoraciones de texto.

Label define las siguientes propiedades:

  • CharacterSpacing, del tipo double, es el espaciado entre los caracteres del texto mostrado.
  • FontAttributes, de tipo FontAttributes, determina el estilo de texto.
  • FontAutoScalingEnabled, de tipo bool, define si el texto reflejará las preferencias de escalado establecidas en el sistema operativo. El valor predeterminado de esta propiedad es true.
  • FontFamily, del tipo string, define la familia de fuentes.
  • FontSize, de tipo double, define el tamaño de fuente.
  • FormattedText, de tipo FormattedString, especifica la presentación de texto con varias opciones de presentación, como fuentes y colores.
  • HorizontalTextAlignment, del tipo TextAlignment, es la alineación horizontal del texto mostrado.
  • LineBreakMode, de tipo LineBreakMode, determina cómo se debe controlar el texto cuando no cabe en una línea.
  • LineHeight, del tipo double, especifica el multiplicador que se aplica en el alto de línea predeterminado al mostrar el texto.
  • MaxLines, de tipo int, indica el número máximo de líneas permitidas en Label.
  • Padding, de tipo Thickness, determina el relleno de la etiqueta.
  • Text, de tipo string, define el texto que se muestra como el contenido de la etiqueta.
  • TextColor, de tipo Color, define el color del texto mostrado.
  • TextDecorations, de tipo TextDecorations, especifica las decoraciones de texto (subrayado y tachado) que se pueden aplicar.
  • TextTransform, de tipo TextTransform, especifica el uso de mayúsculas y minúsculas del texto mostrado.
  • TextType, de tipo TextType, determina si la Label debería mostrar texto sin formato o texto en HTML.
  • VerticalTextAlignment, de tipo TextAlignment, define la alineación vertical del texto mostrado.

Estas propiedades están respaldadas por objetos BindableProperty, lo que significa que pueden ser destinos de los enlaces de datos, y que se les puede aplicar un estilo.

Para obtener información sobre cómo especificar fuentes en un Label, consulta Fuentes.

Creación de una etiqueta

En el siguiente ejemplo se muestra cómo crear una Label.

<Label Text="Hello world" />

El código de C# equivalente es el siguiente:

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

Establecer colores

Las etiquetas se pueden establecer para usar un color de texto específico a través de la propiedad TextColor.

El siguiente ejemplo establece el color de texto de un Label:

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

Para obtener más información acerca de los colores, consulta Colores.

Espaciado entre caracteres

El espaciado de caracteres se puede aplicar a los objetos Label estableciendo la propiedad CharacterSpacingen un valor double:

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

El resultado es que los caracteres del texto mostrado por el Label están separados por unidades independientes del dispositivo espaciadas CharacterSpacing.

Agrega nuevas líneas

Hay dos técnicas principales para forzar el texto en una nueva línea Label, desde XAML:

  1. Use el carácter de fuente de línea unicode, que es " ".
  2. Especifica tu texto mediante la sintaxis del elemento de propiedad.

El siguiente código muestra un ejemplo de ambas 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>

En C#, el texto se puede forzar en una nueva línea con el carácter "\n":

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

Control del truncamiento y ajuste del texto

El ajuste de texto y el truncamiento se pueden controlar estableciendo la propiedad LineBreakMode en un valor de la enumeración LineBreakMode:

  • NoWrap — no encapsula el texto, mostrando solo tanto texto como pueda caber en una línea. Se trata del valor predeterminado de la propiedad LineBreakMode.
  • WordWrap — ajusta el texto en el límite de la palabra.
  • CharacterWrap — ajusta el texto en una nueva línea en un límite de caracteres.
  • HeadTruncation — trunca el encabezado del texto, mostrando el final.
  • MiddleTruncation — muestra el principio y el final del texto, con el reemplazo intermedio por puntos suspensivos.
  • TailTruncation — muestra el principio del texto, truncando el final.

Mostrar un número específico de líneas

El número de líneas mostradas por un Label se puede especificar estableciendo la propiedad MaxLines en un valor int:

  • Cuando MaxLines es -1, que es su valor predeterminado, el Label respeta el valor de la propiedad LineBreakMode para mostrar solo una línea, posiblemente truncada o todas las líneas con todo el texto.
  • Cuando MaxLines es 0, Label no se muestra.
  • Cuando MaxLines es 1, el resultado es idéntico a establecer la propiedadLineBreakMode en NoWrap, HeadTruncation, MiddleTruncation o TailTruncation. Sin embargo, el Label respetará el valor de la propiedad LineBreakMode con respecto a la colocación de puntos suspensivos, si procede.
  • Cuando MaxLines es mayor que 1, el Label se mostrará hasta el número especificado de líneas, respetando el valor de la propiedad LineBreakMode con respecto a la colocación de puntos suspensivos, si procede. Sin embargo, establecer la propiedad MaxLines en un valor mayor que 1 no tiene ningún efecto si la propiedad LineBreakMode está establecida en NoWrap.

En el siguiente ejemplo de código XAML se muestra cómo establecer la propiedad MaxLines en una 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" />

Establecer alto de línea

El alto vertical de un Label se puede personalizar estableciendo la propiedad Label.LineHeight en un valor double.

Nota:

  • En iOS, la propiedad Label.LineHeight cambia el alto de línea del texto que se ajusta a una sola línea y el texto que se ajusta a varias líneas.
  • En Android, la propiedad Label.LineHeight solo cambia el alto de línea del texto que se ajusta a varias líneas.
  • En Windows, la propiedad Label.LineHeight cambia el alto de línea del texto que se ajusta a varias líneas.

En el siguiente ejemplo de código se muestra cómo se establece la propiedad LineHeight en 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" />

En la siguiente captura de pantalla se muestra el resultado de establecer la propiedad Label.LineHeight en 1.8:

Captura de pantalla de ejemplo de altura de línea de Etiquetas.

mostrar HTML

Importante

Mostrar HTML en un Label se limita a las etiquetas HTML admitidas por la plataforma subyacente. Por ejemplo, Android solo admite un subconjunto de etiquetas HTML, centrándose en el estilo básico y el formato de los elementos de nivel de bloque, como <span> y <p>. Para una representación HTML más compleja, considere la posibilidad de usar un WebView o FormattedText.

La clase Label tiene una propiedad TextType, que determina si el objeto Label debería mostrar texto sin formato o texto HTML. La propiedad se debe establecer en uno de los miembros de enumeración TextType.

  • Text indica que Label mostrará texto sin formato y es el valor predeterminado de la propiedad TextType.
  • Html indica que Label mostrará texto HTML.

Por lo tanto, los objetos Label pueden mostrar HTML estableciendo la propiedad TextType a Html, y la propiedad Text en una cadena HTML:

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

En el ejemplo anterior, los caracteres de comillas dobles del HTML deben escaparse mediante el símbolo \.

En XAML, las cadenas HTML se pueden volver ilegibles debido a que además se escapan de los símbolos < y >:

<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 mejorar la legibilidad, el código HTML se puede insertar en una sección 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>

En este ejemplo, la propiedad Text se establece en la cadena HTML insertada en la sección CDATA. Esto funciona porque la propiedad Text es la ContentProperty para la clase Label.

Decorar texto

Las decoraciones de texto subrayado y tachado se pueden aplicar a objetos Label estableciendo la propiedad TextDecorations en uno o varios miembros de enumeración TextDecorations:

  • None
  • Underline
  • Strikethrough

En el siguiente ejemplo se muestra cómo se establece la propiedad 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" />

El código de C# equivalente es el siguiente:

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

En la siguiente captura de pantalla se muestran los miembros de enumeración TextDecorations aplicados a instancias Label:

Captura de pantalla de Etiquetas con decoraciones de texto.

Nota:

Las decoraciones de texto también se pueden aplicar a instancias Span. Para obtener más información sobre la clase Span, consulta Usar texto con formato.

Transformar texto

Un objeto Label puede transformar el uso de mayúsculas y minúsculas de su texto, almacenado en la propiedad Text, estableciendo la propiedad TextTransform en un valor de la enumeración TextTransform. Esta enumeración tiene cuatro valores:

  • None indica que el texto no se transformará.
  • Default: indica que se usará el comportamiento predeterminado para la plataforma. Se trata del valor predeterminado de la propiedad TextTransform.
  • Lowercase indica que el texto se transformará en minúsculas.
  • Uppercase indica que el texto se transformará en mayúsculas.

En el ejemplo siguiente se muestra cómo transformar texto en mayúsculas:

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

Usar texto con formato

Label expone una propiedad FormattedText que permite la presentación de texto con varias fuentes y colores en la misma vista. La propiedad FormattedText es de tipo FormattedString, que consta de una o varias instancias Span establecidas a través de la propiedad Spans.

Nota:

No es posible mostrar HTML en un Span.

Span define las siguientes propiedades:

  • BackgroundColor, de tipo Color, que representa el color del fondo del intervalo.
  • CharacterSpacing, del tipo double, es el espaciado entre los caracteres del texto mostrado.
  • FontAttributes, de tipo FontAttributes, determina el estilo de texto.
  • FontAutoScalingEnabled, de tipo bool, define si el texto reflejará las preferencias de escalado establecidas en el sistema operativo. El valor predeterminado de esta propiedad es true.
  • FontFamily, del tipo string, define la familia de fuentes.
  • FontSize, de tipo double, define el tamaño de fuente.
  • LineHeight, del tipo double, especifica el multiplicador que se aplica en el alto de línea predeterminado al mostrar el texto.
  • Style, de tipo Style, que es el estilo que se va a aplicar al intervalo.
  • Text, de tipo string, define el texto que se muestra como el contenido de Span.
  • TextColor, de tipo Color, define el color del texto mostrado.
  • TextDecorations, de tipo TextDecorations, especifica las decoraciones de texto (subrayado y tachado) que se pueden aplicar.
  • TextTransform, de tipo TextTransform, especifica el uso de mayúsculas y minúsculas del texto mostrado.

Estas propiedades están respaldadas por objetos BindableProperty, lo que significa que pueden ser destinos de los enlaces de datos, y que se les puede aplicar un estilo.

Nota:

La propiedad Span.LineHeight no tiene ningún efecto en Windows.

Además, la propiedad GestureRecognizers se puede usar para definir una colección de reconocedores de gestos que responderán a gestos en Span.

En el ejemplo de XAML siguiente se muestra una propiedad FormattedText que consta de tres instancias 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>

El código de C# equivalente es el siguiente:

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

En la captura de pantalla siguiente se muestra el Label resultante que contiene tres objetos Span:

Captura de pantalla de Etiqueta que consta de tres intervalos.

También Span puede responder a los gestos que se agregan a la colección del intervalo GestureRecognizers. Por ejemplo, se ha agregado un elemento TapGestureRecognizer al segundo Span de los ejemplos anteriores. Por lo tanto, cuando Span se pulsa, TapGestureRecognizer responderá ejecutando el ICommand definido por la propiedad Command. Para obtener más información sobre el reconocimiento de gestos de pulsación, consulta Reconocimiento de un gesto de pulsación.

El texto mostrado por las instancias Label y Span se puede convertir en hipervínculos con el siguiente enfoque:

  1. Establece las propiedades TextColor y TextDecoration de Label o Span.
  2. Agrega un objeto TapGestureRecognizer a la colección GestureRecognizers de Span o Label, cuya propiedad Command se enlaza a un ICommand y cuya propiedad CommandParameter contiene la dirección URL que se va a abrir.
  3. Define el objeto ICommand que ejecutará TapGestureRecognizer
  4. Escribe el código que ejecutará ICommand.

En el ejemplo siguiente se muestra un Label, cuyo contenido se establece a partir de varios 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>

En este ejemplo, las primeras y terceras instancias Span contienen texto, mientras que la segunda Span representa un hipervínculo pulsable. Tiene su color de texto establecido en azul y tiene una decoración de texto subrayado. Esto crea la apariencia de un hipervínculo, como se muestra en la captura de pantalla siguiente:

Captura de pantalla de un hipervínculo.

Cuando se pulsa el hipervínculo, TapGestureRecognizer responderá ejecutando el ICommand definido por su propiedad Command. Además, la dirección URL especificada por la propiedad CommandParameter se pasará a ICommand como parámetro .

El código subyacente de la página XAML contiene la implementación 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 ejecuta el método Launcher.OpenAsync y pasa el valor de propiedad TapGestureRecognizer.CommandParameter como parámetro. El método Launcher.OpenAsync abre la dirección URL en un explorador web. Por lo tanto, el efecto general es que cuando se pulsa el hipervínculo en la página, aparece un explorador web y se navega a la dirección URL asociada al hipervínculo.

El enfoque anterior para crear un hipervínculo requiere escribir código repetitivo cada vez que necesites un hipervínculo en la aplicación. Pero, tanto las clases Spancomo Label se pueden generar con subclases para crear clases HyperlinkLabel y HyperlinkSpan, con el reconocedor de gestos y el código de formato de texto agregado allí.

En el ejemplo siguiente, se muestra una clase 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 clase HyperlinkSpan define una propiedad Url y una BindableProperty asociada, y el constructor establece la apariencia del hipervínculo y el TapGestureRecognizer que responderá cuando se pulse el hipervínculo. Cuando se pulsa un HyperlinkSpan, el TapGestureRecognizer responderá ejecutando el método Launcher.OpenAsync para abrir la dirección URL, especificada por la propiedad Url, en un explorador web.

La clase HyperlinkSpan se puede consumir agregando una instancia de la clase al 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>