Text 块

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

这是正确的控件吗？

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

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

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

创建文本块

• 重要 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 属性设置为字符串值，如前面的示例所示。

还可以通过在 Inlines 属性中放置内联流内容元素来添加内容，如下所示。 （Inlines 是 TextBlock的默认内容属性，因此无需在 XAML 中显式添加它。

<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，可为文本的不同部分启用不同的格式设置。 有关详细信息，请参阅“ 设置文本 格式”部分。 内联 超链接 元素允许向文本添加超链接。 但是，使用 Inlines 还会禁用快速路径文本呈现，下一部分将对此进行讨论。

性能注意事项

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

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

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

注意

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

• Typography：仅各个 Typography 属性的默认值是快速路径。
• LineStackingStrategy：如果 LineHeight 不是 0，则 BaselineToBaseline 值和 MaxHeight 值将禁用快速路径。
• IsTextSelectionEnabled：仅 false 是快速路径。 将此属性设置为 true 禁用快速路径。

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

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

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、前台，以及 CharacterSpacing 更改文本的外观。 还可以使用内联文本元素和 版式 附加属性来设置文本的格式。 这些选项仅影响 TextBlock 在本地显示文本的方式，因此，如果将文本复制并粘贴到 RTF 控件中，则不会应用任何格式设置。

注意

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

Inline 元素

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

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

下面介绍如何使用用 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>

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 Gallery 应用程序，并查看 TextBlock 的实际效果。 WinUI 2 库应用包括大多数 WinUI 2 控件、特性和功能的交互式示例。 通过 Microsoft Store 获取应用，或在 GitHub 上获取源代码。

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

相关文章

• Text 控件
• TextBox class（TextBox 类）
• PasswordBox 类
• String.Length 属性