Text bloco

O bloco Text é o principal controle para exibir texto somente leitura em aplicativos. 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. Você pode acessar e usar facilmente o texto de um bloco de texto em seu aplicativo obtendo 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 com 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 controlo de texto correto, consulte os Text controles.

Criar um bloco de texto

O aplicativo WinUI 3 Gallery inclui exemplos interativos da maioria dos controles, recursos e funcionalidades do WinUI 3. Obtenha o aplicativo no da Microsoft Store ou obtenha o código-fonte em do 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. Esse caminho rápido diminui o uso geral de memória e reduz muito o tempo da CPU para medir e organizar texto. Este caminho rápido aplica-se apenas a 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 Inlines do TextBlock(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 os valores None, CharacterEllipsise WordEllipsis são 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, Foregrounde CharacterSpacing para alterar a aparência do texto. Você também pode usar elementos de texto em linha e Tipografia propriedades associadas para formatar o seu 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.

Tipografia

As propriedades anexadas da classe Typography fornecem acesso a um conjunto de propriedades de tipografia 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>

UWP e WinUI 2

As APIs para esse controle existem no namespace Windows.UI.Xaml.Controls.

Recomendamos usar o WinUI 2 mais recente para obter os estilos, modelos e recursos mais atuais para todos os controles.

Artigos relacionados

• Text controlos
• classe TextBox
• classe PasswordBox
• propriedade String.Length