Bloco de texto

  • Artigo

Bloco de texto é o controle principal para exibir texto somente leitura em aplicativos. Você pode usá-lo para exibir texto de linha única ou de várias linhas, hiperlinks embutidos e texto com formatação, como negrito, itálico ou sublinhado.

Esse é o controle correto?

Um bloco de texto geralmente é mais fácil de usar e fornece melhor desempenho na renderização de texto do que um bloco Rich Text, por isso é o preferido para a maioria do texto da interface do usuário de aplicativo. Você pode facilmente acessar e usar o texto de um bloco de texto em seu aplicativo, obtendo o valor da propriedade Text. Também fornece muitas das mesmas opções de formatação para personalizar como o texto será renderizado.

Embora você possa colocar quebras de linha no texto, o bloco de texto é projetado para exibir um único parágrafo e não dá 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 controle de texto certo, consulte o artigo Controles de texto.

UWP e WinUI 2

Importante

As informações e exemplos neste artigo são otimizados para aplicativos que usam o SDK do Aplicativo Windows e o WinUI 3, mas geralmente são aplicáveis a aplicativos UWP que usam o WinUI 2. Consulte a referência da API da UWP para obter informações e exemplos específicos da plataforma.

Esta seção contém informações necessárias para usar o controle em um aplicativo UWP ou WinUI 2.

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

É recomendável usar a WinUI 2 mais recente para obter os estilos, modelos e recursos mais atuais para todos os controles.

Criar um bloco de texto

Abra o aplicativo Galeria do WinUI 3 e veja o TextBlock em ação.

O aplicativo Galeria da WinUI 3 inclui exemplos interativos da maioria dos controles, recursos e funcionalidades da WinUI 3. Obtenha o aplicativo na Microsoft Store ou o código-fonte no GitHub

Consulte aqui como definir um controle TextBlock simples e configurar sua propriedade Text para 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 da cadeia de caracteres, conforme mostrado no exemplo anterior.

Você também pode adicionar conteúdo ao colocar elementos de conteúdo de fluxo embutidos na propriedade TextBox.Inlines, dessa forma.

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

Elementos derivados da classe Inline, como Bold, Italic, Run, Span e LineBreak, permitem formatações diferentes para diferentes partes do texto. Para obter mais informações, consulte a seção Formatação do texto. O elemento Hyperlink embutido permite adicionar um hiperlink ao seu texto. No entanto, usar Inlines também desabilita a renderização de texto de caminho rápido, que será 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 texto de layout. Esse caminho rápido reduz o uso de memória em geral e reduz consideravelmente o tempo da CPU para medir e organizar o texto. Esse caminho rápido aplica-se somente ao TextBlock. Portanto, sempre que possível, ele deve ter preferência sobre RichTextBlock.

Determinadas condições exigem que o TextBlock faça fallback em caminho de código com mais recursos e uso intenso de CPU para renderização de texto. Para manter a renderização de texto no caminho rápido, siga estas diretrizes para configurar as propriedades listadas aqui.

  • Text: a condição mais importante é que o caminho rápido seja usado somente quando você definir o texto configurando explicitamente a propriedade Text, em XAML ou em código (como mostrado nos exemplos anteriores). Definir o texto pela coleção Inlines do TextBlock (como <TextBlock>Inline text</TextBlock>) desabilitará 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, CharacterEllipsis e WordEllipsis são o caminho rápido. O valor Clip desabilita o caminho rápido.

Nota Antes do Windows 10, versão 1607, propriedades adicionais também afetam o caminho rápido. Se o aplicativo for executado em uma versão anterior do Windows, essas condições também farão o texto ser renderizado no caminho lento. Para mais informações sobre as versões, confira Código adaptável de versão.

  • Typography: somente os valores padrão das diversas propriedades Typography são o caminho rápido.
  • LineStackingStrategy: se LineHeight não for 0, os valores BaselineToBaseline e MaxHeight desabilitarão o caminho rápido.
  • IsTextSelectionEnabled: somente false é o caminho rápido. Configurar essa propriedade como true desabilita o caminho rápido.

Você pode configurar a propriedade DebugSettings.IsTextPerformanceVisualizationEnabled como true durante a depuração para determinar se o texto está usando a renderização de caminho rápido. Quando essa propriedade é configurada como true, o texto que está no caminho rápido aparece na cor verde-claro.

Ponta Esse recurso é explicado detalhadamente nesta sessão do Build 2015- Desempenho XAML: técnicas para maximizar experiências universais de aplicativos do Windows criadas com XAML.

Você geralmente define as configurações de depuração na substituição do método OnLaunched na página code-behind, desta forma.

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 configurado como true, o resultado é semelhante a este.

Texto renderizado no modo de depuração

Cuidado

A cor do texto que não está no caminho rápido não é alterada. Se você tiver texto em seu aplicativo com a cor especificada como verde brilhante, ele ainda será exibido em verde brilhante quando estiver no caminho de renderização mais lento. Tome cuidado para não confundir o texto definido como verde no aplicativo com o texto que está no caminho rápido e verde devido às configurações de depuração.

Formatação do texto

Embora a propriedade Text armazene texto sem formatação, você pode aplicar várias opções de formatação no controle TextBlock para personalizar como o texto será 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 os elementos de texto embutidos e propriedades anexadas Typography para formatar seu texto. Essas opções afetam apenas como TextBlock exibe o texto localmente, portanto, se você copiar e colar o texto em um controle rich text, por exemplo, nenhuma formatação será aplicada.

Observação

Lembre-se de que, conforme observado na seção anterior, os elementos de texto embutidos e os valores de tipografia não padrão não são renderizados no caminho rápido.

Elementos embutidos

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, Span e LineBreak.

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

Consulte como definir algumas cadeias de caracteres de texto formatadas diferentemente em um TextBlock usando Run objetos separados com 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>

Consulte o resultado.

Texto formatado com elementos de execução

Tipografia

As propriedades anexadas da classe Typography fornecem acesso a um conjunto de propriedades de tipografia Microsoft OpenType. Você pode definir essas propriedades anexadas em TextBlock ou nos elementos de texto embutidos 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>

Obter o código de exemplo