文本块

项目
07/04/2024

文本块是用于在应用中显示只读文本的主要控件。可以使用它来显示单行或多行文本、内联超链接和带有加粗、斜体或带下划线格式的文本。

这是正确的控件吗？

文本块通常更易于使用，并且提供比 RTF 块更好的文本呈现性能，因此它最适合大多数应用 UI 文本。通过获取 Text 属性的值，可以轻松访问和使用应用中文本块中的文本。它还提供了许多相同的格式设置选项，用于自定义文本的呈现方式。

虽然可以在文本中放入换行符，但文本块设计为显示一个段落且不支持文本缩进。 需要支持多个段落、多列文本或其他复杂文本布局或嵌入式 UI 元素（如图像）时，请使用 RichTextBlock。

有关选择正确的文本控件的详细信息，请参阅文本控件文章。

UWP 和 WinUI 2

重要

本文中的信息和示例是针对使用 Windows App SDK 和 WinUI 3 的应用优化的，但通常适用于使用 WinUI 2 的 UWP 应用。有关特定于平台的信息和示例，请查看 UWP API 参考。

本部分包含在 UWP 或 WinUI 2 应用中使用该控件所需的信息。

此控件的 API 存在于 Windows.UI.Xaml.Controls 命名空间中。

UWP API：TextBlock 类、Text 属性、Inlines 属性
打开 WinUI 2 库应用并查看 TextBlock 的操作。 WinUI 2 库应用包括大多数 WinUI 2 控件、特性和功能的交互式示例。通过 Microsoft Store 获取应用，或在 GitHub 上获取源代码。

建议使用最新的 WinUI 2 来获取所有控件的最新样式、模板和功能。

创建文本块

重要 API：TextBlock 类、Text 属性、Inlines 属性

打开 WinUI 3 库应用并查看 TextBlock 的操作。

WinUI 3 库应用包括大多数 WinUI 3 控件、特性和功能的交互式示例。通过 Microsoft Store 获取应用，或在 GitHub 上获取源代码

下面介绍如何定义简单的 TextBlock 控件并将其 Text 属性设置为字符串。

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

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

内容模型

可以使用两个属性将内容添加到 TextBlock： Text 和 Inlines。

显示文本的最常见方法是将 Text 属性设置为字符串值，如前面的示例所示。

还可以通过在 TextBox.Inlines 属性中放置内联流内容元素来添加内容，如下所示。

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

派生自 Inline 类的元素，如 Bold、Italic、Run、Span 和 LineBreak，可为文本的不同部分启用不同的格式设置。有关详细信息，请参阅“ 设置文本格式”部分。内联 Hyperlink 元素允许向文本添加超链接。但是，使用内联也会禁用快速路径文本呈现，下一部分对此进行了讨论。

性能注意事项

尽可能使用更高效的代码路径来布局文本。此快速路径既减少了总体内存使用，又大大减少了执行文本测量和排列的 CPU 时间。此快速路径仅适用于 TextBlock，因此应尽可能优先于 RichTextBlock。

某些条件要求 TextBlock 回退到功能更丰富的 CPU 密集型代码路径，以便文本呈现。若要在快速路径上保留文本呈现，请确保在设置此处列出的属性时遵循这些准则。

文本：最重要的条件是，仅在通过显式设置 XAML 或代码中的 Text 属性（如前面的示例所示）来设置文本时，才使用快速路径。由于多种格式的潜在复杂性，通过 TextBlock 的 Inlines 集合（例如 <TextBlock>Inline text</TextBlock>）设置文本将禁用快速路径。
CharacterSpacing：只有默认值 0 是快速路径。
TextTrimming：只有 None、CharacterEllipsis 和 WordEllipsis 值是快速路径。 Clip 值禁用快速路径。

注意：在 Windows 10 版本 1607 之前，其他属性也会影响快速路径。如果你的应用在早期版本的 Windows 上运行，这些条件也会导致文本在慢速路径上呈现。有关版本的详细信息，请参阅版本自适应代码。

版式：只有各种版式属性的默认值是快速路径。
LineStackingStrategy：如果 LineHeight 不是 0， 则 BaselineToBaseline 和 MaxHeight 值将禁用快速路径。
IsTextSelectionEnabled：只有 false 是快速路径。将此属性设置为 true 将禁用快速路径。

可以在调试期间将 DebugSettings.IsTextPerformanceVisualizationEnabled 属性设置为 true ，以确定文本是否使用快速路径呈现。当此属性设置为 true 时，快速路径上的文本将以亮绿色显示。

提示：Build 2015- XAML 性能：关于最大程度地提升使用 XAML 生成的通用 Windows 应用体验的技术中的此会议详细介绍了此功能。

通常，在 App.xaml 的代码隐藏页中设置 OnLaunched 方法重写中的调试设置，如下所示。

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

// ...

}

在此示例中，第一个 TextBlock 是使用快速路径呈现的，而第二个不是。

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

在调试模式下运行此 XAML 时，IsTextPerformanceVisualizationEnabled 设置为 true，结果如下所示。

在调试模式下呈现的文本

注意

不在快速路径上的文本颜色不会更改。如果你的应用中有文本，其颜色指定为亮绿色，则当它位于较慢的呈现路径上时，它仍以亮绿色显示。请注意不要将应用中设置为绿色的文本与快速路径和绿色的文本混淆，因为调试设置。

设置文本格式

虽然 Text 属性存储纯文本，但你可以对 TextBlock 控件应用各种格式选项，以自定义文本在应用中的呈现方式。可以设置标准控件属性，如 FontFamily、FontSize、FontStyle、Foreground 和 CharacterSpacing 以更改文本的外观。还可以使用内联文本元素和版式附加属性设置文本的格式。这些选项仅影响 TextBlock 在本地显示文本的方式，因此，如果将文本复制并粘贴到格式文本控件中，例如，不会应用任何格式设置。

注意

请记住，如上一部分所述，内联文本元素和非默认版式值不会在快速路径上呈现。

内联元素

Microsoft.UI.Xaml.Documents 命名空间提供了各种内联文本元素，可用于设置文本的格式，例如 Bold、Italic、Run、Span 和 LineBreak。

可以在 TextBlock 中显示一系列字符串，其中每个字符串具有不同的格式。为此，可以使用 Run 元素来显示每个字符串及其格式，并使用 LineBreak 元素分隔每个 Run 元素。

下面介绍如何使用与 LineBreak 分隔的 Run 对象在 TextBlock 中定义多个不同格式的文本字符串。

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

下面是结果。

使用 run 元素设置格式的文本

版式

Typography 类的附加属性提供对一组Microsoft OpenType 版式属性的访问权限。可以在 TextBlock 或单个内联文本元素上设置这些附加属性。这些示例显示了这两个示例。

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

获取示例代码

WinUI 库示例 - 以交互式格式查看所有 XAML 控件。

通过

文本块