绘制格式化文本

项目
08/18/2008

更新：2007 年 11 月

本主题概述 FormattedText 对象的功能。该对象为在 Windows Presentation Foundation (WPF) 应用程序中绘制文本提供低级别控制。

本主题包括下列各节。

技术概述
使用 FormattedText 对象
Win32 迁移
相关主题

技术概述

使用 FormattedText 对象可以绘制多行文本，且可以单独对该文本中的每个字符设置格式。下面的示例演示应用了多种格式的文本。

使用 FormattedText 方法显示的文本

使用 FormattedText 对象显示的文本

说明：
对于从 Win32 API 迁移的开发人员，Win32 迁移一节中的表列出了 Win32 DrawText 标志和 Windows Presentation Foundation (WPF) 中的近似等效项。

使用格式化文本的原因

WPF 包括多个用于在屏幕中绘制文本的控件。每个控件都面向不同的方案，并具有自己的功能和限制列表。通常，当需要支持有限的文本（例如用户界面 (UI) 中的简短语句）时，应使用 TextBlock 元素。当需要支持最少的文本时，可以使用 Label。有关更多信息，请参见 Windows Presentation Foundation 中的文档。

FormattedText 对象提供的文本格式设置功能比 Windows Presentation Foundation (WPF) 文本控件提供的相应功能更强大，并且可以在要将文本用作装饰元素时使用。有关更多信息，请参见下一节将格式化文本转换为几何图形。

此外，FormattedText 对象可用于创建面向文本的 DrawingVisual 派生对象。DrawingVisual 是用于呈现形状、图像或文本的轻量绘图类。有关更多信息，请参见使用 DrawingVisual 进行命中测试示例。

使用 FormattedText 对象

若要创建格式化文本，请调用 FormattedText 构造函数以创建一个 FormattedText 对象。一旦创建了初始格式化文本字符串，便可以应用某一范围的格式样式。

使用 MaxTextWidth 属性可以将文本约束为特定宽度。文本将自动换行，以避免超过指定宽度。使用 MaxTextHeight 属性可以将文本约束为特定高度。超过指定高度的文本将显示一个省略号“…”。

显示自动换行和省略号的文本

使用 FormattedText 对象显示的文本

您可以向一个或多个字符应用多种格式样式。例如，您可以调用 SetFontSize 和 SetForegroundBrush 方法来更改文本中前五个字符的格式。

下面的代码示例创建一个 FormattedText 对象，然后向文本应用多种格式化样式。

protected override void OnRender(DrawingContext drawingContext)
{
    string testString = "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor";

    // Create the initial formatted text string.
    FormattedText formattedText = new FormattedText(
        testString,
        CultureInfo.GetCultureInfo("en-us"),
        FlowDirection.LeftToRight,
        new Typeface("Verdana"),
        32,
        Brushes.Black);

    // Set a maximum width and height. If the text overflows these values, an ellipsis "..." appears.
    formattedText.MaxTextWidth = 300;
    formattedText.MaxTextHeight = 240;

    // Use a larger font size beginning at the first (zero-based) character and continuing for 5 characters.
    // The font size is calculated in terms of points -- not as device-independent pixels.
    formattedText.SetFontSize(36 * (96.0 / 72.0), 0, 5);

    // Use a Bold font weight beginning at the 6th character and continuing for 11 characters.
    formattedText.SetFontWeight(FontWeights.Bold, 6, 11);

    // Use a linear gradient brush beginning at the 6th character and continuing for 11 characters.
    formattedText.SetForegroundBrush(
                            new LinearGradientBrush(
                            Colors.Orange,
                            Colors.Teal,
                            90.0),
                            6, 11);

    // Use an Italic font style beginning at the 28th character and continuing for 28 characters.
    formattedText.SetFontStyle(FontStyles.Italic, 28, 28);

    // Draw the formatted text string to the DrawingContext of the control.
    drawingContext.DrawText(formattedText, new Point(10, 0));
}

字号度量单位

如同 Windows Presentation Foundation (WPF) 应用程序中的其他文本对象，FormattedText 对象使用与设备无关的像素作为度量单位。但是，大多数 Win32 应用程序使用磅作为度量单位。如果您要在 Windows Presentation Foundation (WPF) 应用程序中以磅为单位显示文本，需要将与设备无关的单位（每个单位 1/96 英寸）转换为磅。下面的代码示例演示如何执行该转换。

// The font size is calculated in terms of points -- not as device-independent pixels.
formattedText.SetFontSize(36 * (96.0 / 72.0), 0, 5);

将格式化文本转换为几何图形

您可以将带有格式的文本转换为 Geometry 对象，这样便可以创建其他类型的悦目文本。例如，可以基于文本字符串的轮廓创建 Geometry 对象。

使用线性渐变画笔的文本轮廓

下面的几个示例说明了几种通过修改已转换文本的笔画、填充和高光点来创建悦目效果的方法。

将笔画和填充设置为不同颜色的示例

对填充和笔画使用不同颜色的文本

应用于笔画的图像画笔的示例

笔画应用了图像画笔的文本

应用于笔画和高光点的图像画笔的示例

笔画应用了图像画笔的文本

将文本转换为 Geometry 对象时，它不再是字符的集合 - 您不能修改文本字符串中的字符。但是，可以修改已转换文本的笔画和填充属性，以此来影响该文本的外观。笔画指的是已转换文本的轮廓；填充指的是已转换文本的轮廓的内部区域。有关更多信息，请参见如何：创建空心文字。

您还可以将格式化文本转换为 PathGeometry 对象，并使用此对象突出显示文本。例如，您可以将动画应用于 PathGeometry 对象，使此动画沿着格式化文本的轮廓显示。

下面的示例演示已转换为 PathGeometry 对象的格式化文本。经过动画处理的椭圆会沿着所呈现文本的笔画路径显示。

沿着文本的路径几何图形显示的球体

沿着文本路径几何图形运动的球

有关更多信息，请参见如何：针对文本创建 PathGeometry 动画。

将格式化文本转换为 PathGeometry 对象之后，您可以为其创建其他有趣的用法。例如，您可以剪辑视频，以便在格式化文本中显示。有关更多信息，请参见视频文本演示。

在文本的路径几何图形中显示的视频

文本路径几何图形中的视频显示

Win32 迁移

FormattedText 用于绘制文本的功能与 Win32 DrawText 函数的功能相似。对于从 Win32 API 迁移的开发人员，下表列出了 Win32 DrawText 标志和 Windows Presentation Foundation (WPF) 中的近似等效项。

DrawText 标志	WPF 等效项	说明
DT_BOTTOM	Height	使用 Height 属性可以计算相应的 Win32 DrawText 的“y”位置。
DT_CALCRECT	Height、Width	使用 Height 和 Width 属性可以计算输出矩形。
DT_CENTER	TextAlignment	使用值设置为 Center 的 TextAlignment 属性。
DT_EDITCONTROL	无	不需要。间距宽度和最后一行的呈现与在框架编辑控件中相同。
DT_END_ELLIPSIS	Trimming	使用值为 CharacterEllipsis 的 Trimming 属性。使用 WordEllipsis 来获取带有 DT_WORD_ELIPSIS 尾部省略号的 Win32 DT_END_ELLIPSIS。在该情况下，省略号字符仅出现在无法适合于单个行的字中。
DT_EXPAND_TABS	无	不需要。制表符自动扩展为在每 4 个 em 后停止，这大约为 8 个与语言无关的字符的宽度。
DT_EXTERNALLEADING	无	不需要。行距中始终包括外部间隙。使用 LineHeight 属性可以创建用户定义的行距。
DT_HIDEPREFIX	无	不支持。在构造 FormattedText 对象之前从该字符串中移除“&”。
DT_LEFT	TextAlignment	这是默认文本对齐方式。使用值设置为 Left 的 TextAlignment 属性。（仅限 WPF。）
DT_MODIFYSTRING	无	不支持。
DT_NOCLIP	VisualClip	剪辑不会自动发生。如果要剪辑文本，请使用 VisualClip 属性。
DT_NOFULLWIDTHCHARBREAK	无	不支持。
DT_NOPREFIX	无	不需要。字符串中的“&”字符始终作为正常字符进行处理。
DT_PATHELLIPSIS	无	使用值为 WordEllipsis 的 Trimming 属性。
DT_PREFIX	无	不支持。如果要对文本（例如快捷键或链接）使用下划线，请使用 SetTextDecorations 方法。
DT_PREFIXONLY	无	不支持。
DT_RIGHT	TextAlignment	使用值设置为 Right 的 TextAlignment 属性。（仅限 WPF。）
DT_RTLREADING	FlowDirection	将 FlowDirection 属性设置为 RightToLeft。
DT_SINGLELINE	无	不需要。FormattedText 对象的行为就像单行控件那样，除非设置了 MaxTextWidth 属性或者文本包含回车/换行 (CR/LF)。
DT_TABSTOP	无	不支持用户定义的制表位位置。
DT_TOP	Height	不需要。上对齐是默认设置。其他垂直定位值可以通过使用 Height 属性计算相应的 Win32 DrawText“y”位置来定义。
DT_VCENTER	Height	使用 Height 属性可以计算相应的 Win32 DrawText 的“y”位置。
DT_WORDBREAK	无	不需要。对 FormattedText 对象自动断词。您无法禁用它。
DT_WORD_ELLIPSIS	Trimming	使用值为 WordEllipsis 的 Trimming 属性。

请参见

通过