文本格式和布局

2025-03-12

DirectWrite 提供了两个用于设置文本格式的接口：IDWriteTextFormat 和 IDWriteTextLayout。 IDWriteTextFormat 仅描述文本的格式，并且当整个字符串的大小、样式、粗细等相同时使用。另一方面，IDWriteTextLayout 封装文本字符串和字符串指定范围的格式。本文档介绍每个接口及其用法。有关这些接口的创建和方法的详细信息，请参阅 IDWriteTextFormat 和 IDWriteTextLayout 参考页。

本文档包含以下部分：

IDWriteTextFormat
- 修改 IDWriteTextFormat
IDWriteTextLayout
- 设置文本范围的格式
- 呈现选项

IDWriteTextFormat

IDWriteTextFormat 对象用于：

描述呈现时整个字符串的格式。若要呈现具有多种格式的字符串，请使用 IDWriteTextLayout 对象。
创建 IDWriteTextLayout 对象时指定默认文本格式。

若要创建 IDWriteTextFormat 对象，请使用 IDWriteFactory：：CreateTextFormat 方法并指定字体系列、字体集合、字体粗细、字号（以 DIP 为单位）、区域设置名称。

修改 IDWriteTextFormat

创建 IDWriteTextFormat 接口后，无法更改某些值：字体系列、集合、粗细和大小以及区域设置名称。若要更改这些值，必须创建一个新的 IDWriteTextFormat 对象。

IDWriteTextLayout 使你无需重新创建任何属性即可更改上述属性。 IDWriteTextFormat 使你可以对应用于整个文本（如文本对齐方式）进行格式更改。如果要将格式应用于特定字符范围，则应使用 IDWriteTextLayout执行此作。

IDWriteTextFormat 提供了设置文本对齐、流方向、增量制表位、行距、段落对齐、剪裁和换字的方法。创建 IDWriteTextFormat 对象后，可以随时更改这些属性。

IDWriteTextLayout

IDWriteTextLayout 接口，与 IDWriteTextFormat不同，表示文本块和关联的格式。 IDWriteTextFormat 表示初始格式信息。以下示例演示如何使用 IDWriteFactory：：CreateTextLayout创建 IDWriteTextLayout 对象。

// Create a text layout using the text format.
if (SUCCEEDED(hr))
{
    RECT rect;
    GetClientRect(hwnd_, &rect); 
    float width  = rect.right  / dpiScaleX_;
    float height = rect.bottom / dpiScaleY_;

    hr = pDWriteFactory_->CreateTextLayout(
        wszText_,      // The string to be laid out and formatted.
        cTextLength_,  // The length of the string.
        pTextFormat_,  // The text format to apply to the string (contains font information, etc).
        width,         // The width of the layout box.
        height,        // The height of the layout box.
        &pTextLayout_  // The IDWriteTextLayout interface pointer.
        );
}

创建对象后，无法更改 IDWriteTextLayout 对象中的文本。若要更改文本，必须删除现有对象并创建新的 IDWriteTextLayout 对象。

可以使用 IDWriteTextLayout 设置指定文本范围的格式。 IDWriteTextLayout 还提供更改字体样式和粗细的方法，以及添加 OpenType 字体功能和命中测试。有关详细信息和方法的完整列表，请参阅 IDWriteTextLayout 参考页。

设置文本范围的格式

IDWriteTextLayout 提供了几种设置文本范围格式的方法。其中每个方法都采用 DWRITE_TEXT_RANGE 结构作为参数，以指定字符串中的起始文本位置以及要设置格式的范围长度。以下示例演示如何将一系列文本的字体粗细设置为粗体。

// Set the font weight to bold for the first 5 letters.
DWRITE_TEXT_RANGE textRange = {0, 5};

if (SUCCEEDED(hr))
{
    hr = pTextLayout_->SetFontWeight(DWRITE_FONT_WEIGHT_BOLD, textRange);
}

呈现选项

仅使用 IDWriteTextFormat 对象描述的格式的文本可以使用 Direct2D呈现，但是，还有一些用于呈现 IDWriteTextLayout 对象的选项。

可以使用下面的方法呈现由 IDWriteTextLayout 对象描述的字符串。

使用 Direct2D 呈现。
使用自定义文本呈现器呈现。
呈现到 GDI 图面。

通过