RichTextBlock 类

定义

public ref class RichTextBlock sealed : FrameworkElement

/// [Microsoft.UI.Xaml.Markup.ContentProperty(Name="Blocks")]
/// [Windows.Foundation.Metadata.Activatable(65536, "Microsoft.UI.Xaml.WinUIContract")]
/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class RichTextBlock final : FrameworkElement

[Microsoft.UI.Xaml.Markup.ContentProperty(Name="Blocks")]
[Windows.Foundation.Metadata.Activatable(65536, "Microsoft.UI.Xaml.WinUIContract")]
[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.WinUIContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class RichTextBlock : FrameworkElement

Public NotInheritable Class RichTextBlock
Inherits FrameworkElement

<RichTextBlock .../>
-or-
<RichTextBlock ...>
  blocksContent
</RichTextBlock>

继承

Object Platform::Object IInspectable DependencyObject UIElement FrameworkElement RichTextBlock

属性

ContentPropertyAttribute ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

示例

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

本示例演示启用了文本选择和文字换行的 RichTextBlock。

在 XAML 中，内容元素的创建是隐式的，因此可以直接将文本添加到 Paragraph 元素，并将 Paragraph 直接添加到 RichTextBlock 元素。

在代码中，必须显式创建每个 Run 元素，设置其 Text 属性，并将其添加到 Paragraph.Inlines 集合。 然后，将每个 Paragraph 添加到 RichTextBlock.Blocks 集合。

<RichTextBlock IsTextSelectionEnabled="True" TextWrapping="Wrap" Width="200" >
    <Paragraph>
        This is some sample text to show the wrapping behavior.
    </Paragraph>
</RichTextBlock>

// Create a RichTextBlock, a Paragraph and a Run.
RichTextBlock richTextBlock = new RichTextBlock();
Paragraph paragraph = new Paragraph();
Run run = new Run();

// Customize some properties on the RichTextBlock.
richTextBlock.IsTextSelectionEnabled = true;
richTextBlock.TextWrapping = TextWrapping.Wrap;
run.Text = "This is some sample text to show the wrapping behavior.";
richTextBlock.Width = 200;

// Add the Run to the Paragraph, the Paragraph to the RichTextBlock.
paragraph.Inlines.Add(run);
richTextBlock.Blocks.Add(paragraph);

// Add the RichTextBlock to the visual tree (assumes stackPanel is declared in XAML).
stackPanel.Children.Add(richTextBlock);

此示例显示了一个 RichTextBlock，其中自定义了 FontWeight、 FontFamily、 FontStyle、 Foreground 和 SelectionHighlightColor ，用于单个文本运行。

在 XAML 中，内容元素的创建是隐式的，因此可以直接将文本添加到 Paragraph 元素，并将 Paragraph 直接添加到 RichTextBlock 元素。

在代码中，必须显式创建每个 Run 元素，设置其 Text 属性，并将其添加到 Paragraph.Inlines 集合。 然后，将每个 Paragraph 添加到 RichTextBlock.Blocks 集合。

<RichTextBlock IsTextSelectionEnabled="True" SelectionHighlightColor="Pink" 
               FontWeight="Light" FontFamily="Arial" FontStyle="Italic" 
               Foreground="Blue">
    <Paragraph>
        This is some sample text to demonstrate some properties.
    </Paragraph>
</RichTextBlock>

// Create a RichTextBlock, a Paragraph and a Run.
RichTextBlock richTextBlock = new RichTextBlock();
Paragraph paragraph = new Paragraph();
Run run = new Run();

// Customize some properties on the RichTextBlock.
richTextBlock.IsTextSelectionEnabled = true;
richTextBlock.SelectionHighlightColor = new SolidColorBrush(Colors.Pink);
richTextBlock.Foreground = new SolidColorBrush(Colors.Blue);
richTextBlock.FontWeight = FontWeights.Light;
richTextBlock.FontFamily = new FontFamily("Arial");
richTextBlock.FontStyle = Windows.UI.Text.FontStyle.Italic;
run.Text = "This is some sample text to demonstrate some properties.";

//Add the Run to the Paragraph, the Paragraph to the RichTextBlock.
paragraph.Inlines.Add(run);
richTextBlock.Blocks.Add(paragraph);

// Add the RichTextBlock to the visual tree (assumes stackPanel is declared in XAML).
stackPanel.Children.Add(richTextBlock);

此示例显示了一个 RichTextBlock，其中自定义了 FontWeight、 FontFamily、 FontStyle、 Foreground 和 SelectionHighlightColor ，用于不同的文本运行。

在 XAML 中，内容元素的创建是隐式的，因此可以直接将文本添加到 Paragraph 元素，并将 Paragraph 直接添加到 RichTextBlock 元素。

在代码中，必须显式创建每个 Run 元素，设置其 Text 属性，并将其添加到 Paragraph.Inlines 集合。 然后，将每个 Paragraph 添加到 RichTextBlock.Blocks 集合。

<RichTextBlock IsTextSelectionEnabled="True" SelectionHighlightColor="Pink" FontFamily="Arial"  >
    <Paragraph>
        <Run Foreground="Blue" FontWeight="Light" Text="This is some" ></Run>
        <Span FontWeight="SemiBold">
            <Run FontStyle="Italic">sample text to</Run>
            <Run Foreground="Red">demonstrate some properties.</Run>
        </Span>
    </Paragraph>
</RichTextBlock>

RichTextBlock richTextBlock = new RichTextBlock();
richTextBlock.IsTextSelectionEnabled = true;
richTextBlock.SelectionHighlightColor = new SolidColorBrush(Colors.Pink);
richTextBlock.FontFamily = new FontFamily("Arial");

Paragraph paragraph = new Paragraph();
Run run = new Run();
run.Foreground = new SolidColorBrush(Colors.Blue);
run.FontWeight = FontWeights.Light;
run.Text = "This is some";

Span span = new Span();
span.FontWeight = FontWeights.SemiBold;

Run run1 = new Run();
run1.FontStyle = Windows.UI.Text.FontStyle.Italic;
run1.Text = " sample text to ";

Run run2 = new Run();
run2.Foreground = new SolidColorBrush(Colors.Red);
run2.Text = "demonstrate some properties.";

span.Inlines.Add(run1);
span.Inlines.Add(run2);
paragraph.Inlines.Add(run);
paragraph.Inlines.Add(span);
richTextBlock.Blocks.Add(paragraph);

// Add the RichTextBlock to the visual tree (assumes stackPanel is declared in XAML).
stackPanel.Children.Add(richTextBlock);

在这里， RichTextBlock 面向 RichTextBlockOverflow 元素来创建多列文本布局。 然后，第一个 RichTextBlockOverflow 元素面向接收其内容溢出的第二个 RichTextBlockOverflow 元素。 如何计算文本溢出的控制布局因素是父网格的约束宽度和高度，以及将网格划分为 300 像素高度/宽度的三个相等列的 ColumnDefinition 设置。 Overflow 还受 FontSize 和许多其他文本格式属性的影响，这些属性更改文本中的字符。

<Grid x:Name="columnGrid" Background="White" Width="900" Height="300">
    <Grid.ColumnDefinitions>
        <ColumnDefinition/>
        <ColumnDefinition/>
        <ColumnDefinition/>
    </Grid.ColumnDefinitions>
    <RichTextBlock Grid.Column="0" IsTextSelectionEnabled="True" TextAlignment="Justify" 
                   OverflowContentTarget="{x:Bind firstOverflowContainer}" 
                   TextIndent="12"
                   FontSize="12" FontFamily="Segoe UI" Foreground="#2a2a2a" Margin="20,0">
        <Paragraph>
            <Bold><Span Foreground="DarkSlateBlue" FontSize="16">Lorem ipsum dolor sit amet</Span></Bold>, consectetur adipiscing elit. Sed ac mi ipsum. Phasellus vel malesuada mauris. Donec pharetra, enim sit amet mattis tincidunt, felis nisi semper lectus, vel porta diam nisi in augue. Pellentesque lacus tortor, aliquam et faucibus id, rhoncus ut justo. Sed id lectus odio, eget pulvinar diam. Suspendisse eleifend ornare libero, in luctus purus aliquet non. Sed interdum, sem vitae rutrum rhoncus, felis ligula ultrices sem, in eleifend eros ante id neque. Vivamus quam lorem, varius vitae porta mollis, placerat quis est. Aenean eget sagittis massa. Sed tellus turpis, ullamcorper eget imperdiet vel, faucibus vel nisl. Nunc sed suscipit quam. Vivamus convallis faucibus dignissim. Fusce sollicitudin, quam vel cursus mattis, nisl velit tristique sapien, ac vestibulum ante arcu a nisl. Vestibulum commodo gravida ante at tincidunt. Vestibulum in ornare nunc. Nullam ut lorem vitae dui placerat lacinia sit amet a arcu. Nulla sit amet odio nisi. Praesent erat urna, venenatis ac adipiscing vel, congue at lectus. Proin ac metus at quam luctus ultricies.
        </Paragraph>
        <Paragraph>
            <Italic>This is an inline image.</Italic>
            <InlineUIContainer>
                <Border Background="Black">
                    <Image Source="Assets/SmallLogo.png" Height="30" Width="30"/>
                </Border>
            </InlineUIContainer> 
            Nam vitae ligula non ligula suscipit semper. Duis sed nulla metus, id hendrerit velit. Curabitur dolor purus, bibendum eu cursus lacinia, interdum vel augue. Aenean euismod eros et sapien vehicula dictum. Duis ullamcorper, turpis nec feugiat tincidunt, dui erat luctus risus, aliquam accumsan lacus est vel quam. Nunc lacus massa, varius eget accumsan id, congue sed orci. Duis dignissim hendrerit egestas. Proin ut turpis magna, sit amet porta erat. Nunc semper metus nec magna imperdiet nec vestibulum dui fringilla. Sed sed ante libero, nec porttitor mi. Ut luctus, neque vitae placerat egestas, urna leo auctor magna, sit amet ultricies ipsum felis quis sapien. Proin eleifend varius dui, at vestibulum nunc consectetur nec. Mauris nulla elit, ultrices a sodales non, aliquam ac est. Quisque sit amet risus nulla. Quisque vestibulum posuere velit, vitae vestibulum eros scelerisque sit amet. In in risus est, at laoreet dolor. Nullam aliquet pellentesque convallis. Ut vel tincidunt nulla. Mauris auctor tincidunt auctor.
        </Paragraph>
    </RichTextBlock>
    <RichTextBlockOverflow x:Name="firstOverflowContainer" Grid.Column="1" Margin="20,0"
                           OverflowContentTarget="{x:Bind secondOverflowContainer}"/>
    <RichTextBlockOverflow x:Name="secondOverflowContainer" Grid.Column="2" Margin="20,0"/>
</Grid>

注解

RichTextBlock 控件显示只读文本，并为高级文本布局提供多项功能。 需要支持段落、内联 UI 元素或溢出文本时，请使用 RichTextBlock。

TextBlock 提供更简单的内容模型，因此通常更易于使用，并且比 RichTextBlock 提供更好的文本呈现性能。 它还提供了许多相同的格式设置选项，用于自定义文本的呈现方式。 但是，RichTextBlock 提供了 TextBlock 不提供的多个独特功能。

有关详细信息和示例，请参阅 RichTextBlock 控件指南。

段落和格式

RichTextBlock 的内容属性是基于 Paragraph 元素的 Blocks 属性。 通过设置 TextIndent 属性设置段落缩进。

可以使用 版式 类的文本元素和附加属性将字符和段落格式应用于 RichTextBlock 中的文本。 例如，可以将 粗体、 斜体和 下划线 应用于控件中文本的任何部分。

内联 UI 元素

可以在 RichTextBlock 的内容中使用 InlineUIContainer 在文本中嵌入派生自 UIElement（如图像）的元素。

溢出内容

可以将 RichTextBlock 与 RichTextBlockOverflow 元素配合使用来创建高级页面布局，例如多列文本。 RichTextBlockOverflow 元素的内容始终来自 RichTextBlock 元素。 通过将 RichTextBlock 或其他 RichTextBlockOverflow 的 OverflowContentTarget 设置为 RichTextBlockOverflow 来链接 RichTextBlockOverflow 元素。

字体回退

RichTextBlock 的默认 FontFamily 为 Segoe UI，默认 FontSize 为 15 个与设备无关的像素（DIP）。 默认情况下，RichTextBlock 使用字体回退机制显示未包含在指定字体中的字形。 如果 RichTextBlock 中所需的字形在指定字体中不可用，则字体回退机制会浏览系统上的字体列表，以尝试以其他字体显示所需的字符。

另请参阅

• Paragraph
• OverflowContentTarget
• RichTextBlockOverflow
• OverflowContentTarget
• RTF 块概述
• XAML 文本显示示例