TextBlock 类

定义

public ref class TextBlock sealed : FrameworkElement

/// [Microsoft.UI.Xaml.Markup.ContentProperty(Name="Inlines")]
/// [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 TextBlock final : FrameworkElement

[Microsoft.UI.Xaml.Markup.ContentProperty(Name="Inlines")]
[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 TextBlock : FrameworkElement

Public NotInheritable Class TextBlock
Inherits FrameworkElement

<TextBlock ...>text</TextBlock>
-or-
<TextBlock>
  oneOrMoreInlineElements
</TextBlock>
-or-
<TextBlock .../>

继承

Object Platform::Object IInspectable DependencyObject UIElement FrameworkElement TextBlock

属性

ContentPropertyAttribute ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

示例

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

此示例演示启用了文本选择并启用文本换行的 TextBlock。

呈现的文本如下所示：

<TextBlock Text="This text demonstrates the wrapping behavior of a TextBlock." Width="240"
           IsTextSelectionEnabled="True" TextWrapping="Wrap"/>

TextBlock textBlock = new TextBlock();
textBlock.Text = "This text demonstrates the wrapping behavior of a TextBlock.";
textBlock.Width = 240;
textBlock.IsTextSelectionEnabled = true;
textBlock.TextWrapping = TextWrapping.Wrap;

// Add TextBlock to the visual tree.
rootPanel.Children.Add(textBlock);

此示例演示如何使用单个文本 运行 自定义 TextBlock 的外观。 “ FontWeight”、“ FontFamily”、“ FontStyle”、“ 前景色 ”和 “SelectionHighlightColor ”属性是自定义的。

呈现的文本如下所示：

<TextBlock Text="This text demonstrates some TextBlock properties." 
           IsTextSelectionEnabled="True" 
           SelectionHighlightColor="Green" 
           Foreground="Blue" 
           FontWeight="Light" 
           FontFamily="Arial" 
           FontStyle="Italic"/>

TextBlock textBlock = new TextBlock();
textBlock.Text = "This text demonstrates some TextBlock properties.";
textBlock.IsTextSelectionEnabled = true;
textBlock.SelectionHighlightColor = new SolidColorBrush(Windows.UI.Colors.Green);
textBlock.Foreground = new SolidColorBrush(Windows.UI.Colors.Blue);
textBlock.FontWeight = Windows.UI.Text.FontWeights.Light;
textBlock.FontFamily = new FontFamily("Arial");
textBlock.FontStyle = Windows.UI.Text.FontStyle.Italic;

// Add TextBlock to the visual tree.
rootPanel.Children.Add(textBlock);

此示例演示如何在 TextBlock 中自定义不同的内联元素。

呈现的文本如下所示：

<TextBlock IsTextSelectionEnabled="True" SelectionHighlightColor="Green" FontFamily="Arial">
    <Run Foreground="Blue" FontWeight="Light" Text="This text demonstrates "></Run>
    <Span FontWeight="SemiBold">
        <Run FontStyle="Italic">the use of inlines </Run>
        <Run Foreground="Red">with formatting.</Run>
    </Span>
</TextBlock>

TextBlock textBlock = new TextBlock();
textBlock.IsTextSelectionEnabled = true;
textBlock.SelectionHighlightColor = new SolidColorBrush(Windows.UI.Colors.Green);
textBlock.FontFamily = new FontFamily("Arial");

// For Run and Span, add 'using Windows.UI.Xaml.Documents;'
Windows.UI.Xaml.Documents.Run run = new Run();
run.Foreground = new SolidColorBrush(Windows.UI.Colors.Blue);
run.FontWeight = Windows.UI.Text.FontWeights.Light;
run.Text = "This text demonstrates ";

Windows.UI.Xaml.Documents.Span span = new Span();
span.FontWeight = Windows.UI.Text.FontWeights.SemiBold;

Run run1 = new Run();
run1.FontStyle = Windows.UI.Text.FontStyle.Italic;
run1.Text = "the use of inlines ";

Run run2 = new Run();
run2.Foreground = new SolidColorBrush(Windows.UI.Colors.Red);
run2.Text = "with formatting.";

span.Inlines.Add(run1);
span.Inlines.Add(run2);
textBlock.Inlines.Add(run);
textBlock.Inlines.Add(span);

// Add TextBlock to the visual tree.
rootPanel.Children.Add(textBlock);

此示例演示如何使用内联超链接。 有关详细信息，请参阅 超链接。

<TextBlock><Hyperlink xml:space="preserve" NavigateUri="http://www.bing.com"> Hyperlink to Bing </Hyperlink></TextBlock>

// Create a TextBlock this is needed to put the hyperlink inside
TextBlock textBlock = new TextBlock();

// Create a Hyperlink and a Run. 
// The Run is used as the visible content of the hyperlink.
Hyperlink hyperlink = new Hyperlink();
Run run = new Run();

// Set the Text property on the run. 
// This is the visible text of the hyperlink.
run.Text = " Hyperlink to Bing ";

// Add the Run to the Hyperlink. 
hyperlink.Inlines.Add(run);

// Set the URI for the Hyperlink. 
hyperlink.NavigateUri = new Uri("http://www.bing.com");

// Add the Hyperlink to the TextBlock.
textBlock.Inlines.Add(hyperlink);

// Add TextBlock to the visual tree.        
rootPanel.Children.Add(textBlock);

以下示例演示如何使用 LineStackingStrategy 属性确定如何为 TextBlock 的文本行创建行框。 第一个 TextBlock 的 LineStackingStrategy 值为 MaxHeight，第二个 TextBlock 的 值为 BlockLineHeight，第三个 TextBlock 的 值为 BaselineToBaseline。

呈现的文本如下所示：

<StackPanel>

<!-- This TextBlock has a LineStackingStrategy set to "MaxHeight". -->
<TextBlock FontFamily="Verdana"
           LineStackingStrategy="MaxHeight" 
           LineHeight="10" 
           Width="500" 
           TextWrapping="Wrap" >
    Use the <Run FontSize="30">LineStackingStrategy</Run> property to determine how a line box is
    created for each line. A value of <Run FontSize="20">MaxHeight</Run> specifies that the stack
    height is the smallest value that contains all the inline elements on that line when those
    elements are properly aligned. A value of <Run FontSize="20">BlockLineHeight</Run> specifies
    that the stack height is determined by the block element LineHeight property value. A value of 
    <Run FontSize="20">BaselineToBaseline</Run> specifies that the stack height is determined by adding 
    LineHeight to the baseline of the previous line.
</TextBlock>

<!-- With a margin pushing down 20 pixels, draw a line just above the second textblock. -->
<!-- The fonts will reach above the LineHeight size and over the line. -->
<StackPanel Margin="0,20,0,0" HorizontalAlignment="Center">
    <Line Stroke="Green"  X2="500" />
</StackPanel>

<!-- Here is the same TextBlock but the LineStackingStrategy is set to "BlockLineHeight". -->
<TextBlock FontFamily="Verdana"
           LineStackingStrategy="BlockLineHeight" 
           LineHeight="10" 
           Width="500" 
           TextWrapping="Wrap">
    Use the <Run FontSize="30">LineStackingStrategy</Run> property to determine how a line box is
    created for each line. A value of <Run FontSize="20">MaxHeight</Run> specifies that the stack
    height is the smallest value that contains all the inline elements on that line when those
    elements are properly aligned. A value of <Run FontSize="20">BlockLineHeight</Run> specifies
    that the stack height is determined by the block element LineHeight property value. A value of 
    <Run FontSize="20">BaselineToBaseline</Run> specifies that the stack height is determined by adding 
    LineHeight to the baseline of the previous line.
</TextBlock>

<!-- With a margin pushing down 20 pixels, draw a line just above the third textblock. -->
<StackPanel Margin="0,20,0,0" HorizontalAlignment="Center">
    <Line Stroke="Green"  X2="500" />
</StackPanel>

<!-- Here is the same TextBlock but the LineStackingStrategy is set to "BaselineToBaseline". -->
<TextBlock FontFamily="Verdana"
           LineStackingStrategy="BaselineToBaseline" 
           LineHeight="10" 
           Width="500" 
           TextWrapping="Wrap">
    Use the <Run FontSize="30">LineStackingStrategy</Run> property to determine how a line box is
    created for each line. A value of <Run FontSize="20">MaxHeight</Run> specifies that the stack
    height is the smallest value that contains all the inline elements on that line when those
    elements are properly aligned. A value of <Run FontSize="20">BlockLineHeight</Run> specifies
    that the stack height is determined by the block element LineHeight property value. A value of 
    <Run FontSize="20">BaselineToBaseline</Run> specifies that the stack height is determined by adding 
    LineHeight to the baseline of the previous line.
</TextBlock>

</StackPanel>

注解

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

TextBlock 通常更易于使用，并且提供比 RichTextBlock 更好的文本呈现性能，因此它最适合大多数应用 UI 文本。 它还提供了许多相同的格式设置选项，用于自定义文本的呈现方式。 虽然可以在文本中放入换行符，但 TextBlock 旨在显示一个段落且不支持文本缩进。 如果需要支持多个段落、多列文本或嵌入式 UI 元素（如图像），请考虑 使用 RichTextBlock 。

文本性能

从Windows 10开始，对 TextBlock 进行了性能改进，减少了总体内存使用，并大大减少了执行文本测量和排列的 CPU 时间。 若要详细了解这些性能改进以及如何确保使用它们，请参阅 TextBlock 控件指南的性能注意事项部分。

内置文本样式

可以使用随平台一起提供的Windows 10文本样式，将文本的样式与系统中使用的文本对齐。 下面介绍如何使用内置样式与Windows 10类型渐变对齐。 有关详细信息，请参阅 XAML 主题资源。

<TextBlock Text="Header" Style="{StaticResource HeaderTextBlockStyle}"/>
<TextBlock Text="SubHeader" Style="{StaticResource SubheaderTextBlockStyle}"/>
<TextBlock Text="Title" Style="{StaticResource TitleTextBlockStyle}"/>
<TextBlock Text="SubTitle" Style="{StaticResource SubtitleTextBlockStyle}"/>
<TextBlock Text="Base" Style="{StaticResource BaseTextBlockStyle}"/>
<TextBlock Text="Body" Style="{StaticResource BodyTextBlockStyle}"/>
<TextBlock Text="Caption" Style="{StaticResource CaptionTextBlockStyle}"/>

呈现的文本如下所示：

颜色字体

默认情况下，TextBlock 支持显示颜色字体。 系统上的默认颜色字体是 Segoe UI 表情符号，TextBlock 将回退到此字体以显示颜色字形。 有关详细信息，请参阅 IsColorFontEnabled 属性。

<TextBlock FontSize="30">Hello ☺⛄☂♨⛅</TextBlock>

呈现的文本如下所示：

另请参阅

• RichTextBlock
• TextBox
• 文本块概述
• 控件列表