Text bloco

O bloco Text é o principal controlo para exibir texto apenas de leitura em aplicações. Você pode usá-lo para exibir texto de linha única ou multilinha, hiperlinks embutidos e texto com formatação como negrito, itálico ou sublinhado.

Será este o controlo correto?

Um bloco de texto normalmente é mais fácil de usar e oferece melhor desempenho de renderização de texto do que um bloco de rich text, por isso é preferido para a maioria do texto da interface do usuário do aplicativo. Podes facilmente aceder e usar texto de um bloco de texto na tua aplicação ao conseguires o valor da propriedade Text. Ele também fornece muitas das mesmas opções de formatação para personalizar como o texto é renderizado.

Embora você possa colocar quebras de linha no texto, o bloco de texto foi projetado para exibir um único parágrafo e não oferece suporte a recuo de texto. Use um RichTextBlock quando precisar de suporte para vários parágrafos, texto de várias colunas ou outros layouts de texto complexos, ou elementos de interface do usuário embutidos, como imagens.

Para obter mais informações sobre como escolher o controle de texto correto, consulte o artigo controlesText.

Criar um bloco de texto

A aplicação WinUI 3 Gallery inclui exemplos interativos de controlos e funcionalidades WinUI. Descarrega a aplicação na Microsoft Store ou navega pelo código-fonte no GitHub.

Veja como definir um controle TextBlock simples e definir sua propriedade Text como uma cadeia de caracteres.

<TextBlock Text="Hello, world!" />

TextBlock textBlock1 = new TextBlock();
textBlock1.Text = "Hello, world!";

Modelo de conteúdo

Há duas propriedades que você pode usar para adicionar conteúdo a um TextBlock: Text e Inlines.

A maneira mais comum de exibir texto é definir a propriedade Text como um valor de cadeia de caracteres, conforme mostrado no exemplo anterior.

Você também pode adicionar conteúdo colocando elementos de conteúdo de fluxo embutido na propriedade Inlines, desta forma. (Inlines é a propriedade de conteúdo padrão de um TextBlock, portanto, você não precisa adicioná-lo explicitamente em XAML.)

<TextBlock>Text can be <Bold>bold</Bold>, <Underline>underlined</Underline>, 
    <Italic>italic</Italic>, or a <Bold><Italic>combination</Italic></Bold>.</TextBlock>

Os elementos derivados da classe Inline, como Bold, Italic, Run, Spane LineBreak, permitem uma formatação diferente para diferentes partes do texto. Para obter mais informações, consulte a seção Formatação de texto. O elemento Hyperlink embutido permite adicionar um hiperlink ao texto. No entanto, o uso de Inlines também desabilita a renderização de texto de caminho rápido, que é discutida na próxima seção.

Considerações sobre desempenho

Sempre que possível, o XAML usa um caminho de código mais eficiente para layout de texto. Este caminho rápido reduz tanto o uso total de memória como diminui significativamente o tempo da CPU para medir e organizar o texto. Esse caminho rápido se aplica apenas ao TextBlock, por isso deve ser preferido quando possível sobre RichTextBlock.

Certas condições exigem que TextBlock recorra a um caminho de código mais rico em recursos e com uso intensivo de CPU para renderização de texto. Para manter a renderização de texto no caminho rápido, siga estas diretrizes ao definir as propriedades listadas aqui.

• Text: A condição mais importante é que o caminho rápido seja usado somente quando você define texto, definindo explicitamente a propriedade Text, seja em XAML ou em código (como mostrado nos exemplos anteriores). Definir o texto através da coleção TextBlock do Inlines(como <TextBlock>Inline text</TextBlock>) desativará o caminho rápido, devido à complexidade potencial de vários formatos.
• CharacterSpacing: Somente o valor padrão de 0 é o caminho rápido.
• TextTrimming: Somente None, CharacterEllipsis e WordEllipsis são valores de caminho rápido. O valor Clip desativa o caminho rápido.

Você pode definir a propriedade DebugSettings.IsTextPerformanceVisualizationEnabled como true durante a depuração para determinar se o texto está usando renderização de caminho rápido. Quando essa propriedade é definida como true, o texto que está no caminho rápido é exibido em uma cor verde brilhante.

Normalmente, você define as configurações de depuração na substituição do método OnLaunched na página code-behind para App.xaml, como este.

protected override void OnLaunched(LaunchActivatedEventArgs e)
{
#if DEBUG
    if (System.Diagnostics.Debugger.IsAttached)
    {
        this.DebugSettings.IsTextPerformanceVisualizationEnabled = true;
    }
#endif

// ...

}

Neste exemplo, o primeiro TextBlock é renderizado usando o caminho rápido, enquanto o segundo não.

<StackPanel>
    <TextBlock Text="This text is on the fast path."/>
    <TextBlock>This text is NOT on the fast path.</TextBlock>
<StackPanel/>

Quando você executa esse XAML no modo de depuração com IsTextPerformanceVisualizationEnabled definido como true, o resultado tem esta aparência.

Formatação de texto

Embora a propriedade Text armazene texto sem formatação, você pode aplicar várias opções de formatação ao controle TextBlock para personalizar como o texto é renderizado em seu aplicativo. Você pode definir propriedades de controle padrão como FontFamily, FontSize, FontStyle, Foreground e CharacterSpacing para alterar a aparência do texto. Você também pode usar elementos de texto embutidos e propriedades anexadas de tipografia para formatar o texto. Essas opções afetam apenas como o TextBlock exibe o texto localmente, portanto, se você copiar e colar o texto em um controle de rich text, por exemplo, nenhuma formatação será aplicada.

Inline elementos

O namespace Microsoft.UI.Xaml.Documents fornece uma variedade de elementos de texto embutidos que você pode usar para formatar seu texto, como Bold, Italic, Run, Spane LineBreak.

Você pode exibir uma série de cadeias de caracteres em um TextBlock, onde cada cadeia de caracteres tem formatação diferente. Você pode fazer isso usando um elemento Run para exibir cada cadeia de caracteres com sua formatação e separando cada elemento Run com um elemento LineBreak.

Veja como definir várias cadeias de caracteres de texto formatadas de forma diferente em um TextBlock usando Run objetos separados por um LineBreak.

<TextBlock FontFamily="Segoe UI" Width="400" Text="Sample text formatting runs">
    <LineBreak/>
    <Run Foreground="Gray" FontFamily="Segoe UI Light" FontSize="24">
        Segoe UI Light 24
    </Run>
    <LineBreak/>
    <Run Foreground="Teal" FontFamily="Georgia" FontSize="18" FontStyle="Italic">
        Georgia Italic 18
    </Run>
    <LineBreak/>
    <Run Foreground="Black" FontFamily="Arial" FontSize="14" FontWeight="Bold">
        Arial Bold 14
    </Run>
</TextBlock>

Aqui está o resultado.

Typography

As propriedades associadas da classe Typography fornecem access a um conjunto de propriedades tipográficas do Microsoft OpenType. Você pode definir essas propriedades anexadas no TextBlockou em elementos de texto inline individuais. Estes exemplos mostram ambos.

<TextBlock Text="Hello, world!"
           Typography.Capitals="SmallCaps"
           Typography.StylisticSet4="True"/>

TextBlock textBlock1 = new TextBlock();
textBlock1.Text = "Hello, world!";
Typography.SetCapitals(textBlock1, FontCapitals.SmallCaps);
Typography.SetStylisticSet4(textBlock1, true);

<TextBlock>12 x <Run Typography.Fraction="Slashed">1/3</Run> = 4.</TextBlock>

Artigos relacionados

• Text controlos
• Classe TextBox
• Classe PasswordBox
• Propriedade String.Length