RTF 文本块

2025-07-22

RTF 文本块提供了多种适用于高级文本布局的功能，你可以在需要支持段落、内联 UI 元素或复杂文本布局时使用它们。

这是正确的控件吗？

如果需要支持多个段落、多列或其他复杂文本布局或者内联 UI 元素（例如图像），请使用 RichTextBlock。

使用 TextBlock 显示应用中的大部分只读文本。你可以使用它来显示单行或多行文本、内联超链接以及带有粗体、斜体或下划线格式的文本。 TextBlock 提供较简单的内容模型，因此通常也更易于使用，并且它比 RichTextBlock 提供文本呈现性能更好。它适用于大部分应用 UI 文本。虽然可以在文本中放入换行符，但 TextBlock 旨在显示一个段落且不支持文本缩进。

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

建议

请参阅版式和字体指南。

创建富文本块

重要 API：RichTextBlock 类、RichTextBlockOverflow 类、Paragraph 类、Typography 类

打开 WinUI 3 库应用并查看 RichTextBlock 运行情况

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

RichTextBlock 的内容属性为 Blocks 属性，它通过 Paragraph 元素支持基于段落的文本。它没有可以用来轻松访问应用中控件的文本内容的 Text 属性。但是，RichTextBlock 提供了多个 TextBlock 没有提供的独特功能。

RichTextBlock 支持：

多个段落。通过设置 TextIndent 属性设置段落缩进。
内联 UI 元素。使用 InlineUIContainer 显示与文本内联的 UI 元素，如图像。
溢出容器。使用 RichTextBlockOverflow 元素创建多列文本布局。

段落

使用 Paragraph 元素定义要在 RichTextBlock 控件中显示的文本块。每个 RichTextBlock 应至少包括一个 Paragraph。

通过设置 RichTextBlock.TextIndent 属性，可以在 RichTextBlock 中设置所有段落的缩进量。通过将 Paragraph.TextIndent 属性设置为不同值，可以在 RichTextBlock 中为特定段落替代此设置。

<RichTextBlock TextIndent="12">
  <Paragraph TextIndent="24">First paragraph.</Paragraph>
  <Paragraph>Second paragraph.</Paragraph>
  <Paragraph>Third paragraph. <Bold>With an inline.</Bold></Paragraph>
</RichTextBlock>

内联 UI 元素

借助 InlineUIContainer 类，可以嵌入任何与文本内联的 UIElement。常见方案是防止与文本内联的图像，但还可以使用交互式元素，例如 Button 或 CheckBox。

如果需要在同一位置嵌入多个元素内联，请考虑将面板用作单个 InlineUIContainer 子项，然后将多个元素放入该面板中。

本示例显示如何使用 InlineUIContainer 将图像插入 RichTextBlock 中。

<RichTextBlock>
    <Paragraph>
        <Italic>This is an inline image.</Italic>
        <InlineUIContainer>
            <Image Source="Assets/Square44x44Logo.png" Height="30" Width="30"/>
        </InlineUIContainer>
        Mauris auctor tincidunt auctor.
    </Paragraph>
</RichTextBlock>

溢出容器

可以将 RichTextBlock 与 RichTextBlockOverflow 元素结合使用，以创建多列或其他高级页面布局。 RichTextBlockOverflow 元素的内容始终来自 RichTextBlock 元素。链接 RichTextBlockOverflow 元素的方法是将其设置为 RichTextBlock 的 OverflowContentTarget 或另一个 RichTextBlockOverflow。

以下是一个创建两列布局的简单示例。查看示例部分以获取更复杂的示例。

<Grid>
    <Grid.ColumnDefinitions>
        <ColumnDefinition/>
        <ColumnDefinition/>
    </Grid.ColumnDefinitions>
    <RichTextBlock Grid.Column="0" 
                   OverflowContentTarget="{Binding ElementName=overflowContainer}" >
        <Paragraph>
            Proin ac metus at quam luctus ultricies.
        </Paragraph>
    </RichTextBlock>
    <RichTextBlockOverflow x:Name="overflowContainer" Grid.Column="1"/>
</Grid>

设置文本格式

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

内联元素

Microsoft.UI.Xaml.Documents 命名空间提供了可用于设置文本格式的各种内联文本元素，如 Bold、Italic、Run、Span 和 LineBreak。将格式设置应用到文本各个部分的典型方法是将文本放入 Run 或 Span 元素中，然后在该元素上设置属性。

在下面的段落中，第一个短语显示为粗体、蓝色、16pt 文本。

<Paragraph>
    <Bold><Span Foreground="DarkSlateBlue" FontSize="16">Lorem ipsum dolor sit amet</Span></Bold>
    , consectetur adipiscing elit.
</Paragraph>

版式

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

<RichTextBlock Typography.StylisticSet4="True">
    <Paragraph>
        <Span Typography.Capitals="SmallCaps">Lorem ipsum dolor sit amet</Span>
        , consectetur adipiscing elit.
    </Paragraph>
</RichTextBlock>

UWP 和 WinUI 2

要点

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

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

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

UWP API：RichTextBlock 类、RichTextBlockOverflow 类、Paragraph 类、Typography 类
打开 WinUI 2 库应用并查看 RichTextBox 的应用情况。 WinUI 2 库应用包括大多数 WinUI 2 控件、特性和功能的交互式示例。通过 Microsoft Store 获取应用，或在 GitHub 上获取源代码。

建议使用最新的 WinUI 2 来获取所有控件的最新样式和模板。 WinUI 2.2 或更高版本包含此控件的使用圆角的新模板。有关详细信息，请参阅圆角半径。

文本控件

面向设计人员

面向开发人员 (XAML)

面向开发人员（其他）

String.Length 属性