高级文本格式

Windows Presentation Foundation （WPF）提供了一组可靠的 API，用于在应用程序中包括文本。 布局和用户界面（UI）API（如 TextBlock）为文本呈现提供最常用的和常规用途元素。 绘图 API（如 GlyphRunDrawing 和 FormattedText）提供了在绘图中包含带格式文本的方法。 在最高级级别，WPF 提供了一个可扩展的文本格式设置引擎，用于控制文本呈现的各个方面，例如文本存储管理、文本运行格式管理和嵌入式对象管理。

本主题介绍 WPF 文本格式。 它侧重于客户端实现和使用 WPF 文本格式设置引擎。

说明

本文档中的所有代码示例都可以在 高级文本格式设置示例中找到。

先决条件

本主题假定你熟悉用于文本演示的高级 API。 大多数用户方案不需要本主题中讨论的高级文本格式 API。 有关不同文本 API 的简介，请参阅 WPF中的 文档。

高级文本格式

WPF 中的文本布局和 UI 控件提供格式属性，使你可以轻松地在应用程序中包括带格式的文本。 这些控件公开许多属性来处理文本的呈现，其中包括其字样、大小和颜色。 在一般情况下，这些控件可以处理应用程序中的大多数文本呈现。 但是，某些高级方案需要控制文本存储和文本呈现。 WPF 为此提供了可扩展的文本格式设置引擎。

WPF 中找到的高级文本格式设置功能包括文本格式设置引擎、文本存储、文本运行和格式设置属性。 文本格式化引擎 TextFormatter 创建用于展示的文本行。 这是通过启动行格式设置过程并调用文本格式化程序的 FormatLine来实现的。 文本格式化程序通过调用文本存储的 GetTextRun 方法从文本存储中检索文本运行。 然后，TextRun 对象由文本格式化程序形成为 TextLine 对象，并提供给应用程序进行检查或显示。

使用文本格式化程序

TextFormatter 是 WPF 文本格式设置引擎，提供格式设置和中断文本行的服务。 文本格式化程序可以处理不同的文本字符格式和段落样式，并包括对国际文本布局的支持。

与传统文本 API 不同，TextFormatter 通过一组回调方法与文本布局客户端交互。 它要求客户端在 TextSource 类的实现中提供这些方法。 下图说明了客户端应用程序与 TextFormatter之间的文本布局交互。

文本格式化程序用于从文本存储中检索格式化文本行，这是 TextSource的实现。 这是通过使用 Create 方法首先创建文本格式化程序实例来完成的。 此方法创建文本格式化程序实例，并设置最大行高和宽度值。 创建文本格式化程序的实例后，通过调用 FormatLine 方法启动行创建过程。 TextFormatter 回叫到文本源以检索文本和格式化参数，该参数用于运行构成行的文本。

在以下示例中，将显示文本存储的格式设置过程。 TextFormatter 对象用于从文本存储中检索文本行，然后格式化文本行以便绘制到 DrawingContext。

// Create a DrawingGroup object for storing formatted text.
textDest = new DrawingGroup();
DrawingContext dc = textDest.Open();

// Update the text store.
_textStore.Text = textToFormat.Text;
_textStore.FontRendering = _currentRendering;

// Create a TextFormatter object.
TextFormatter formatter = TextFormatter.Create();

// Format each line of text from the text store and draw it.
while (textStorePosition < _textStore.Text.Length)
{
   // Create a textline from the text store using the TextFormatter object.
   using (TextLine myTextLine = formatter.FormatLine(
       _textStore,
       textStorePosition,
       96*6,
       new GenericTextParagraphProperties(_currentRendering),
       null))
   {
       // Draw the formatted text into the drawing context.
       myTextLine.Draw(dc, linePosition, InvertAxes.None);

       // Update the index position in the text store.
       textStorePosition += myTextLine.Length;

       // Update the line position coordinate for the displayed line.
       linePosition.Y += myTextLine.Height;
   }
}

// Persist the drawn text content.
dc.Close();

// Display the formatted text in the DrawingGroup object.
myDrawingBrush.Drawing = textDest;

' Create a DrawingGroup object for storing formatted text.
textDest = New DrawingGroup()
Dim dc As DrawingContext = textDest.Open()

' Update the text store.
_textStore.Text = textToFormat.Text
_textStore.FontRendering = _currentRendering

' Create a TextFormatter object.
Dim formatter As TextFormatter = TextFormatter.Create()

' Format each line of text from the text store and draw it.
Do While textStorePosition < _textStore.Text.Length
   ' Create a textline from the text store using the TextFormatter object.
   Using myTextLine As TextLine = formatter.FormatLine(_textStore, textStorePosition, 96*6, New GenericTextParagraphProperties(_currentRendering), Nothing)
       ' Draw the formatted text into the drawing context.
       myTextLine.Draw(dc, linePosition, InvertAxes.None)

       ' Update the index position in the text store.
       textStorePosition += myTextLine.Length

       ' Update the line position coordinate for the displayed line.
       linePosition.Y += myTextLine.Height
   End Using
Loop

' Persist the drawn text content.
dc.Close()

' Display the formatted text in the DrawingGroup object.
myDrawingBrush.Drawing = textDest

实现客户端文本存储

扩展文本格式设置引擎时，需要实现和管理文本存储的所有方面。 这不是一项微不足道的任务。 文本存储负责跟踪文本运行属性、段落属性、嵌入对象和其他类似内容。 它还提供具有 TextRun 对象的文本格式化程序，该文本格式化程序用于创建 TextLine 对象。

若要处理文本存储的虚拟化，文本存储必须派生自 TextSource。 TextSource 定义文本格式化程序用于从文本存储中检索文本段的方法。 GetTextRun 是文本格式化程序用于检索行格式化中使用的文本片段的方法。 对 GetTextRun 的调用由文本格式化程序重复进行，直到出现以下条件之一：

• 返回一个 TextEndOfLine 或一个子类。

• 文本行的累积宽度超过了在调用生成文本格式器时或在调用文本格式器的 FormatLine 方法时指定的最大行宽。

• 返回一个 Unicode 换行符序列，例如“CF”、“LF”或“CRLF”。

提供文本运行

文本格式设置过程的核心是文本格式化程序与文本存储之间的交互。 TextSource 的实现提供具有 TextRun 对象的文本格式化程序，以及用于格式化文本运行的属性。 此交互由文本格式化程序调用的 GetTextRun 方法处理。

下表显示了一些预定义 TextRun 对象。

TextRun 类型	用法
TextCharacters	专用文本运行，用于将字符标志符号的表示形式传回给文本格式化程序。
TextEmbeddedObject	专用文本运行，用于提供其中的度量、命中测试和绘制将作为整体执行的内容，例如文本中的按钮或图像。
TextEndOfLine	专用文本运行，用于对行尾进行标记。
TextEndOfParagraph	用于标记段落结束的专用文本流。
TextEndOfSegment	用于对段尾进行标记的专用文本运行，例如结束受前一次 TextModifier 运行影响的作用域。
TextHidden	专用文本运行，用于对一系列隐藏字符进行标记。
TextModifier	专用文本运行，用于在其范围内修改文本运行属性。 范围延伸至下一个匹配的 TextEndOfSegment 文本段，或下一个 TextEndOfParagraph。

任何预定义 TextRun 对象都可以进行子类化。 这样，文本源就可以为文本格式化程序提供包含自定义数据的文本片段。

以下示例演示 GetTextRun 方法。 此文本存储将 TextRun 对象返回到要处理的文本格式化程序。

// Used by the TextFormatter object to retrieve a run of text from the text source.
public override TextRun GetTextRun(int textSourceCharacterIndex)
{
   // Make sure text source index is in bounds.
   if (textSourceCharacterIndex < 0)
      throw new ArgumentOutOfRangeException("textSourceCharacterIndex", "Value must be greater than 0.");
   if (textSourceCharacterIndex >= _text.Length)
   {
      return new TextEndOfParagraph(1);
   }

   // Create TextCharacters using the current font rendering properties.
   if (textSourceCharacterIndex < _text.Length)
   {
      return new TextCharacters(
         _text,
         textSourceCharacterIndex,
         _text.Length - textSourceCharacterIndex,
         new GenericTextRunProperties(_currentRendering));
   }

   // Return an end-of-paragraph if no more text source.
   return new TextEndOfParagraph(1);
}

' Used by the TextFormatter object to retrieve a run of text from the text source.
Public Overrides Function GetTextRun(ByVal textSourceCharacterIndex As Integer) As TextRun
   ' Make sure text source index is in bounds.
   If textSourceCharacterIndex < 0 Then
      Throw New ArgumentOutOfRangeException("textSourceCharacterIndex", "Value must be greater than 0.")
   End If
   If textSourceCharacterIndex >= _text.Length Then
      Return New TextEndOfParagraph(1)
   End If

   ' Create TextCharacters using the current font rendering properties.
   If textSourceCharacterIndex < _text.Length Then
      Return New TextCharacters(_text, textSourceCharacterIndex, _text.Length - textSourceCharacterIndex, New GenericTextRunProperties(_currentRendering))
   End If

   ' Return an end-of-paragraph if no more text source.
   Return New TextEndOfParagraph(1)
End Function

说明

在此示例中，文本存储为所有文本提供相同的文本属性。 高级文本存储需要实现自己的范围管理，以允许单个字符具有不同的属性。

指定格式设置属性

TextRun 对象是使用文本存储提供的属性格式化的。 这些属性分为两种类型：TextParagraphProperties 和 TextRunProperties。 TextParagraphProperties 处理段落包含属性，例如 TextAlignment 和 FlowDirection。 TextRunProperties 是每个在段落内运行的文本可能不同的属性，例如前景画笔、Typeface 和字号。 若要实现自定义段落和自定义文本运行属性类型，应用程序必须分别创建派生自 TextParagraphProperties 和 TextRunProperties 的类。

另请参阅

• WPF 中的版式
• WPF 中的文档