# 复杂文本绘制与显示（C/C++）

在进行文本绘制时，可以通过选择合适的字体、大小和颜色完成简单文本的绘制与显示；此外，还支持通过设置其他丰富的样式、语言、段落等进行复杂文本的绘制。

复杂文本绘制主要包含以下几个场景：

* 多语言文本绘制与显示

* 多行文本绘制与显示

* 多样式文本绘制与显示

* 样式的拷贝、绘制与显示

## 多语言文本绘制与显示

多语言支持是全球化应用的基础。多语言文本绘制需要支持不同语言的字符集及其独特的显示需求，例如右到左语言（如阿拉伯语）或竖排文本（如中文）。开发者需要理解不同语言的渲染特性，确保文本的正确显示。

在多语言文本使用的场景下，主要通过指定TextStyle文本样式中的**locale**字段来实现，可直接通过locale字段的值优先匹配对应字体，跳过遍历列表匹配字体的过程，从而降低匹配时间和内存使用。

### 接口说明

多语言文本绘制的相关接口如下所示，详细接口说明请参考[drawing_text_typography.h](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-drawing-text-typography-h)。

|接口定义|描述|
|:---------------------------------------------------------------------------------------------|:-------------|
|void OH_Drawing_SetTypographyTextLocale(OH_Drawing_TypographyStyle* style, const char* locale)|设置指定排版样式的语言环境。|

### 开发步骤

画布Canvas对象具体可见[画布的获取与绘制结果的显示](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/canvas-get-result-draw-c)。

    // 创建一个 TypographyStyle，创建 TypographyCreate 时需要使用
    OH_Drawing_TypographyStyle *typoStyle = OH_Drawing_CreateTypographyStyle();
    // 设置文本对齐方式为居中
    OH_Drawing_SetTypographyTextAlign(typoStyle, TEXT_ALIGN_CENTER);
    // 设置 locale 为中文
    OH_Drawing_SetTypographyTextLocale(typoStyle, "zh-Hans");

    // 设置文字颜色、大小、字重，不设置 TextStyle 会使用 TypographyStyle 中的默认 TextStyle
    OH_Drawing_TextStyle *txtStyle = OH_Drawing_CreateTextStyle();
    OH_Drawing_SetTextStyleColor(txtStyle, OH_Drawing_ColorSetArgb(0xFF, 0x00, 0x00, 0x00));
    OH_Drawing_SetTextStyleFontSize(txtStyle, DIV_TEN(width_));
    OH_Drawing_SetTextStyleFontWeight(txtStyle, FONT_WEIGHT_400);

    // 创建 FontCollection，FontCollection 用于管理字体匹配逻辑
    OH_Drawing_FontCollection *fc = OH_Drawing_CreateSharedFontCollection();
    // 使用 FontCollection 和 之前创建的 TypographyStyle 创建 TypographyCreate。TypographyCreate 用于创建 Typography
    OH_Drawing_TypographyCreate *handler = OH_Drawing_CreateTypographyHandler(typoStyle, fc);

    // 将之前创建的 TextStyle 加入 handler 中
    OH_Drawing_TypographyHandlerPushTextStyle(handler, txtStyle);
    // 设置文本内容，并将文本添加到 handler 中
    const char *text = "你好，中文\n";
    OH_Drawing_TypographyHandlerAddText(handler, text);

    // 通过 handler 创建一个 Typography
    OH_Drawing_Typography *typography = OH_Drawing_CreateTypography(handler);
    // 设置页面最大宽度
    double maxWidth = width_;
    OH_Drawing_TypographyLayout(typography, maxWidth);
    // 将文本绘制到画布上
    OH_Drawing_TypographyPaint(typography, cCanvas_, 0, DIV_TEN(width_));

    // 释放内存
    OH_Drawing_DestroyTypographyStyle(typoStyle);
    OH_Drawing_DestroyTextStyle(txtStyle);
    OH_Drawing_DestroyFontCollection(fc);
    OH_Drawing_DestroyTypographyHandler(handler);
    OH_Drawing_DestroyTypography(typography);

### 效果展示

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/c2/v3/Ws28-9IaTO67ix9k096_TA/zh-cn_image_0000002749493356.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=44E6BB6274B1F1935953C5FEBC25A197F49E17EA2574F9D1551642280F3FBB91)

## 多行文本绘制与显示

多行文本相对于单行文本比较复杂，一般针对多行文本，需要进行文本排版、断词策略设置、文本对齐方式、最大行数限制等，主要通过设置段落样式实现。

### 接口说明

多行文本绘制的相关接口如下所示，详细接口说明请参考[drawing_text_typography.h](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-drawing-text-typography-h)。

|接口定义|描述|
|:---------------------------------------------------------------------------------------------------|:---------|
|void OH_Drawing_SetTypographyTextAlign(OH_Drawing_TypographyStyle* style, int align)|设置文本对齐方式。|
|void OH_Drawing_SetTypographyTextWordBreakType(OH_Drawing_TypographyStyle* style, int wordBreakType)|设置单词的断词方式。|
|void OH_Drawing_SetTypographyTextMaxLines(OH_Drawing_TypographyStyle* style, int lineNumber)|设置文本最大行数。|

### 开发步骤

以下以断行策略为 BREAK_ALL 的场景为例，其余策略同理。

    // 创建 FontCollection，FontCollection 用于管理字体匹配逻辑
    OH_Drawing_FontCollection *fc = OH_Drawing_CreateSharedFontCollection();

    // 设置文字颜色、大小、字重，不设置 TextStyle 会使用 TypographyStyle 中的默认 TextStyle
    OH_Drawing_TextStyle *txtStyle = OH_Drawing_CreateTextStyle();
    OH_Drawing_SetTextStyleColor(txtStyle, OH_Drawing_ColorSetArgb(0xFF, 0x00, 0x00, 0x00));
    OH_Drawing_SetTextStyleFontSize(txtStyle, DIV_TWENTY(width_));
    OH_Drawing_SetTextStyleFontWeight(txtStyle, FONT_WEIGHT_400);

    // 设置文本内容
    const char *text =
        "Nunc quis augue viverra, venenatis arcu eu, gravida odio. Integer posuere nisi quis ex pretium, a dapibus "
        "nisl gravida. Mauris lacinia accumsan enim, non tempus ligula. Mauris iaculis dui eu nisi tristique, in porta "
        "urna varius. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Mauris "
        "congue nibh mi, vel ultrices ex volutpat et. Aliquam consectetur odio in libero tristique, a mattis ex "
        "mollis. Praesent et nisl iaculis, facilisis metus nec, faucibus lacus. Duis nec dolor at nibh eleifend "
        "tempus. Nunc et enim interdum, commodo eros ac, pretium sapien. Pellentesque laoreet orci a nunc pharetra "
        "pharetra.";

    // 创建一个断词策略为 BREAK_ALL 的 TypographyStyle
    OH_Drawing_TypographyStyle *typoStyle = OH_Drawing_CreateTypographyStyle();
    // 设置文本对齐方式为居中
    OH_Drawing_SetTypographyTextAlign(typoStyle, TEXT_ALIGN_CENTER);
    // 设置断词策略为 WORD_BREAK_TYPE_BREAK_ALL
    OH_Drawing_SetTypographyTextWordBreakType(typoStyle, OH_Drawing_WordBreakType::WORD_BREAK_TYPE_BREAK_ALL);
    // 设置最大行数为 10，行数大于 10 的部分不显示
    OH_Drawing_SetTypographyTextMaxLines(typoStyle, 10);

    // 使用之前创建的 FontCollection 和 TypographyStyle 创建 TypographyCreate。TypographyCreate 用于创建 Typography
    OH_Drawing_TypographyCreate *handler = OH_Drawing_CreateTypographyHandler(typoStyle, fc);
    // 将之前创建的 TextStyle 加入 handler
    OH_Drawing_TypographyHandlerPushTextStyle(handler, txtStyle);
    // 将文本添加到 handler 中
    OH_Drawing_TypographyHandlerAddText(handler, text);

    OH_Drawing_Typography *typography = OH_Drawing_CreateTypography(handler);
    // 设置页面最大宽度
    double maxWidth = width_;
    OH_Drawing_TypographyLayout(typography, maxWidth);
    // 将文本绘制到画布上
    OH_Drawing_TypographyPaint(typography, cCanvas_, 0, DIV_TEN(width_));

    // 释放内存
    OH_Drawing_DestroyFontCollection(fc);
    OH_Drawing_DestroyTextStyle(txtStyle);
    OH_Drawing_DestroyTypographyStyle(typoStyle);
    OH_Drawing_DestroyTypographyHandler(handler);
    OH_Drawing_DestroyTypography(typography);

|BREAK_ALL|BREAK_WORD|
|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/d4/v3/HxWdPkPoTKy9DDYQjD3zDQ/zh-cn_image_0000002779092415.jpg?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=6C9A2452D738F32FB4DC52142CB577E82213B5808CD53A96E18E6115F3035D5B)|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/ea/v3/2u8bCL_ZSDerKu429xYQKg/zh-cn_image_0000002778932557.jpg?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=29C9685C3CE4ABB6EF75BF5C70F51C5125466D3C592C19534A2999B03AF2F8BF)|

|BREAK_HYPHEN（locale：未设置）|BREAK_HYPHEN（locale：en-gb）|BREAK_HYPHEN（locale：en-us）|
|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/2a/v3/EaLB9FXPQjO8rqQyWO4abg/zh-cn_image_0000002749333476.jpg?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=8B6080CA3CFD387D3B9CBA759EAA7A93D1AA6DB163CD460FB9CC85F37116E7B5)|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/55/v3/T1yBJSX-RP68QoEDNWGU4Q/zh-cn_image_0000002749493358.jpg?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=4F8161E2F30AE662A80E8DEB0521A7FD1B82C5F1ECAC737B99FF3826C78021AF)|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/51/v3/cATcwfajRYee3VikF48HoQ/zh-cn_image_0000002779092417.jpg?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=3A7C2EE9C86A316997EF89E219C93ED719AC18F7A302E647C03490E12C2EFD5C)|

## 多样式文本绘制与显示

除基本文字、排版属性之外，针对应用中不同文本的设计，开发者可能需要设置使用不同的绘制样式或能力，以凸显对应文本的独特表现或风格，此时可以结合使用多种绘制样式进行文本的渲染。

当前支持的多样式绘制及各绘制样式侧重效果如下：

* **装饰线样式绘制：** 主要通过不同的线条样式对文本进行装饰，可以使文本更加突出，富有表现力。

* **字体特征绘制：** 主要通过字体的变化，包括粗细、斜体等特征来改变文本的外观，增强文本的可读性和美观性。

* **可变字体绘制：** 对应提供文本在不同的显示环境和设备上灵活调整的能力，可满足更为精细的视觉效果。

* **文本阴影绘制：** 主要通过在文本周围添加阴影效果，以提升文本的层次感和立体感，从而使文本更具吸引力。

* **占位符绘制：** 可以在不确定文本内容时保持文本布局的稳定性，使得文本显示更为流畅和自然。

* **自动间距绘制：** 可以在一些字符混排切换的地方自动添加额外间距，提升阅读体验。

* **渐变色绘制：** 可以为文字提供颜色渐变效果，增强文字表现力。

* **垂直对齐：** 调整文本在垂直方向排版位置，提升排版质量。

* **上下标：** 可以将任意字符处理成上标或下标，更精准表达文本含义。

* **高对比度文字绘制：** 主要通过将深色文字变黑、浅色文字变白，增强文本的对比效果。

* **行高调整：** 调整行高可改变文本行的垂直间距，使行间距更松散或更紧凑，显著改善文本垂直截断问题，提高可读性。

* **行间距调整：** 通过调整行间距的方式可以实现行高调整一样的效果，优化阅读体验。

* **省略号样式设置：** 在文本内容超出显示区域时，可以使用省略号截断文本，支持头部、中部、尾部以及多行省略模式。

* **文字换行方式设置：** 文本排版时支持不同的断行策略，可根据场景选择合适的换行方式。

* **行首标点压缩：** 在排版中，通过开启行首标点压缩功能，将行首标点符号进行挤压处理，避免标点占用行首空间，提升排版紧凑度。

### 装饰线

**装饰线**是指在文本上方、下方或中间添加的装饰性线条，当前支持上划线、下划线、删除线。

可以通过添加文本装饰线，提升文本的视觉效果和可读性。

使用装饰线需要初始化装饰线样式对象，并添加到文本样式中，从而在文本绘制时生效。

|接口定义|描述|
|:--------------------------------------------------------------------------------------------|:---------------------------------------------------------------------|
|void OH_Drawing_SetTextStyleDecoration(OH_Drawing_TextStyle* style, int decoration)|设置指定文本样式中的装饰线类型，只能设置一个装饰线类型，添加多个需要使用OH_Drawing_AddTextStyleDecoration。|
|void OH_Drawing_SetTextStyleDecorationStyle(OH_Drawing_TextStyle* style, int decorationStyle)|设置指定文本样式中的装饰线样式。|
|void OH_Drawing_SetTextStyleDecorationColor(OH_Drawing_TextStyle* style, uint32_t color)|设置指定文本样式中的装饰线颜色。|

示例及示意效果如下所示：

    // 创建一个TypographyStyle创建Typography时需要使用
    OH_Drawing_TypographyStyle *typoStyle = OH_Drawing_CreateTypographyStyle();
    // 设置文本对齐方式为居中
    OH_Drawing_SetTypographyTextAlign(typoStyle, TEXT_ALIGN_CENTER);
    // 设置文本内容
    const char *text = "Hello World Drawing\n";

    // 设置文字颜色、大小、字重，不设置 TextStyle 会使用 TypographyStyle 中的默认 TextStyle
    OH_Drawing_TextStyle *txtStyleWithDeco = OH_Drawing_CreateTextStyle();
    OH_Drawing_SetTextStyleColor(txtStyleWithDeco, OH_Drawing_ColorSetArgb(0xFF, 0x00, 0x00, 0x00));
    OH_Drawing_SetTextStyleFontSize(txtStyleWithDeco, DIV_TEN(width_));
    OH_Drawing_SetTextStyleFontWeight(txtStyleWithDeco, FONT_WEIGHT_400);
    // 设置装饰线为 LINE_THROUGH
    OH_Drawing_SetTextStyleDecoration(txtStyleWithDeco, TEXT_DECORATION_LINE_THROUGH);
    // 设置装饰线样式为 WAVY
    OH_Drawing_SetTextStyleDecorationStyle(txtStyleWithDeco, TEXT_DECORATION_STYLE_WAVY);
    // 设置装饰线颜色
    OH_Drawing_SetTextStyleDecorationColor(txtStyleWithDeco, OH_Drawing_ColorSetArgb(0xFF, 0x6F, 0xFF, 0xFF));

    // 创建一个不带装饰线的 TextStyle 用于对比
    OH_Drawing_TextStyle *txtStyleNoDeco = OH_Drawing_CreateTextStyle();
    // 设置文字颜色、大小、字重，不设置 TextStyle 会使用 TypographyStyle 中的默认 TextStyle
    OH_Drawing_SetTextStyleColor(txtStyleNoDeco, OH_Drawing_ColorSetArgb(0xFF, 0x00, 0x00, 0x00));
    OH_Drawing_SetTextStyleFontSize(txtStyleNoDeco, DIV_TEN(width_));
    OH_Drawing_SetTextStyleFontWeight(txtStyleNoDeco, FONT_WEIGHT_400);

    // 创建 FontCollection，FontCollection 用于管理字体匹配逻辑
    OH_Drawing_FontCollection *fc = OH_Drawing_CreateSharedFontCollection();
    // 使用 FontCollection 和 之前创建的 TypographyStyle 创建 TypographyCreate。TypographyCreate 用于创建 Typography
    OH_Drawing_TypographyCreate *handler = OH_Drawing_CreateTypographyHandler(typoStyle, fc);

    // 加入带有装饰线的文本样式
    OH_Drawing_TypographyHandlerPushTextStyle(handler, txtStyleWithDeco);
    // 将文本添加到 handler 中
    OH_Drawing_TypographyHandlerAddText(handler, text);

    // 后续加入的不带装饰线的文本样式
    OH_Drawing_TypographyHandlerPushTextStyle(handler, txtStyleNoDeco);
    // 将文本添加到 handler 中
    OH_Drawing_TypographyHandlerAddText(handler, text);

    OH_Drawing_Typography *typography = OH_Drawing_CreateTypography(handler);
    // 设置页面最大宽度
    double maxWidth = width_;
    OH_Drawing_TypographyLayout(typography, maxWidth);
    // 将文本绘制到画布上
    OH_Drawing_TypographyPaint(typography, cCanvas_, 0, DIV_TEN(width_));

    // 释放内存
    OH_Drawing_DestroyTypographyStyle(typoStyle);
    OH_Drawing_DestroyTextStyle(txtStyleWithDeco);
    OH_Drawing_DestroyTextStyle(txtStyleNoDeco);
    OH_Drawing_DestroyFontCollection(fc);
    OH_Drawing_DestroyTypographyHandler(handler);
    OH_Drawing_DestroyTypography(typography);

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/7e/v3/wFXVTm6XTDerX43LRs1dWg/zh-cn_image_0000002778932559.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=8195B0B89CEF81A25928E0B7C217C7D9F2C1B8583B3370A418D82CC16679A378)

### 字体特征

**字体特征**绘制专注于在文本渲染过程中对字体特征（如粗体、斜体、字体变种等）的处理，允许字体在不同的排版场景下表现出不同的效果，可用于增强文本的表现力，使其更符合设计和阅读需求。

常见的**FontFeature**包含有liga、frac、case等，需要对应的ttf文件支持才能正常使能。

|接口定义|描述|
|:-----------------------------------------------------------------------------------------------|:-----------------|
|void OH_Drawing_TextStyleAddFontFeature(OH_Drawing_TextStyle* style, const char* tag, int value)|设置文本样式中指定字体特征是否启用。|

示例及示意效果如下所示：

    // 创建一个 TypographyStyle，创建 TypographyCreate 时需要使用
    OH_Drawing_TypographyStyle *typoStyle = OH_Drawing_CreateTypographyStyle();
    // 设置文本对齐方式为居中
    OH_Drawing_SetTypographyTextAlign(typoStyle, TEXT_ALIGN_CENTER);
    // 设置文本内容
    const char *text = "1/2 1/3 1/4\n";

    // 设置文字颜色、大小、字重，不设置TextStyle无法绘制出文本
    OH_Drawing_TextStyle *txtStyleWithFeature = OH_Drawing_CreateTextStyle();
    OH_Drawing_SetTextStyleColor(txtStyleWithFeature, OH_Drawing_ColorSetArgb(0xFF, 0x00, 0x00, 0x00));
    OH_Drawing_SetTextStyleFontSize(txtStyleWithFeature, DIV_TEN(width_));
    OH_Drawing_SetTextStyleFontWeight(txtStyleWithFeature, FONT_WEIGHT_900);
    // 设置启用frac font feature，此功能将斜线分隔的数字替换为普通（对角线）分数。
    OH_Drawing_TextStyleAddFontFeature(txtStyleWithFeature, "frac", 1);

    // 创建一个不带字体特征的 TextStyle 用于对比
    OH_Drawing_TextStyle *txtStyleNoFeature = OH_Drawing_CreateTextStyle();
    // 设置文字颜色、大小、字重。不设置 TextStyle 无法绘制出文本
    OH_Drawing_SetTextStyleColor(txtStyleNoFeature, OH_Drawing_ColorSetArgb(0xFF, 0x00, 0x00, 0x00));
    OH_Drawing_SetTextStyleFontSize(txtStyleNoFeature, DIV_TEN(width_));
    OH_Drawing_SetTextStyleFontWeight(txtStyleNoFeature, FONT_WEIGHT_900);

    // 创建 FontCollection，FontCollection 用于管理字体匹配逻辑
    OH_Drawing_FontCollection *fc = OH_Drawing_CreateSharedFontCollection();
    // 使用 FontCollection 和 之前创建的 TypographyStyle 创建 TypographyCreate。TypographyCreate 用于创建 Typography
    OH_Drawing_TypographyCreate *handler = OH_Drawing_CreateTypographyHandler(typoStyle, fc);

    // 加入带有字体特征的文本样式
    OH_Drawing_TypographyHandlerPushTextStyle(handler, txtStyleWithFeature);
    // 将文本添加到 handler 中
    OH_Drawing_TypographyHandlerAddText(handler, text);
    // 弹出之前添加的 TextStyle
    OH_Drawing_TypographyHandlerPopTextStyle(handler);

    // 后续加入的不带字体特征的文本样式
    OH_Drawing_TypographyHandlerPushTextStyle(handler, txtStyleNoFeature);
    // 将文本添加到 handler 中
    OH_Drawing_TypographyHandlerAddText(handler, text);
    // 弹出之前添加的 TextStyle
    OH_Drawing_TypographyHandlerPopTextStyle(handler);

    OH_Drawing_Typography *typography = OH_Drawing_CreateTypography(handler);
    // 设置页面最大宽度
    double maxWidth = width_;
    OH_Drawing_TypographyLayout(typography, maxWidth);
    // 将文本绘制到画布上
    OH_Drawing_TypographyPaint(typography, cCanvas_, 0, DIV_TEN(width_));

    // 释放内存
    OH_Drawing_DestroyTypographyStyle(typoStyle);
    OH_Drawing_DestroyTextStyle(txtStyleWithFeature);
    OH_Drawing_DestroyTextStyle(txtStyleNoFeature);
    OH_Drawing_DestroyFontCollection(fc);
    OH_Drawing_DestroyTypographyHandler(handler);
    OH_Drawing_DestroyTypography(typography);

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/79/v3/oLnLeebJTyCXAHZtWj7cKg/zh-cn_image_0000002749333478.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=72D734E3B2C97E863EF3AB9FCC36EE94E35DAA58B0635ECDD78385CA938A8B96)

### 可变字体

**可变字体**是一种在一个字体文件中包含多个字形变体的字体格式，允许在一个字体文件内灵活地调整字体的各种属性（如字重、字宽、斜体等）。

与传统字体文件（每种变体需要一个独立的文件）不同，可变字体在一个字体文件中包含多个变体轴，可通过使用可变字体实现文本渲染绘制时的平滑过渡。

|接口定义|描述|
|:----------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------|
|void OH_Drawing_TextStyleAddFontVariation(OH_Drawing_TextStyle* style, const char* axis, const float value)|添加可变字体属性。对应的字体文件（.ttf文件）需要支持可变调节，此接口才能生效。当对应的字体不支持可变调节时，此接口调用不生效。|

示例及示意效果如下所示：

    // 创建一个 TypographyStyle 创建 Typography 时需要使用
    OH_Drawing_TypographyStyle *typoStyle = OH_Drawing_CreateTypographyStyle();
    // 设置文本对齐方式为居中
    OH_Drawing_SetTypographyTextAlign(typoStyle, TEXT_ALIGN_CENTER);
    // 设置文字内容
    const char *text = "Hello World Drawing\n";

    OH_Drawing_TextStyle *txtStyleWithVar = OH_Drawing_CreateTextStyle();
    // 设置可变字体的字重为800，在字体文件支持的情况下，还可以设置"slnt", "wdth"
    OH_Drawing_TextStyleAddFontVariation(txtStyleWithVar, "wght", 800);
    // 设置文字颜色、大小、字重，不设置 TextStyle 会使用 TypographyStyle 中的默认 TextStyle
    OH_Drawing_SetTextStyleColor(txtStyleWithVar, OH_Drawing_ColorSetArgb(0xFF, 0x00, 0x00, 0x00));
    OH_Drawing_SetTextStyleFontSize(txtStyleWithVar, DIV_TEN(width_));
    // 此处设置字重不生效，将被可变字体的字重覆盖
    OH_Drawing_SetTextStyleFontWeight(txtStyleWithVar, FONT_WEIGHT_400);

    // 创建一个不带可变字体的 TextStyle 用于对比
    OH_Drawing_TextStyle *txtStyleNoVar = OH_Drawing_CreateTextStyle();
    // 设置文字颜色、大小、字重，不设置 TextStyle 会使用 TypographyStyle 中的默认 TextStyle
    OH_Drawing_SetTextStyleColor(txtStyleNoVar, OH_Drawing_ColorSetArgb(0xFF, 0x00, 0x00, 0x00));
    OH_Drawing_SetTextStyleFontSize(txtStyleNoVar, DIV_TEN(width_));
    OH_Drawing_SetTextStyleFontWeight(txtStyleNoVar, FONT_WEIGHT_400);

    // 创建 FontCollection，FontCollection 用于管理字体匹配逻辑
    OH_Drawing_FontCollection *fc = OH_Drawing_CreateSharedFontCollection();
    // 使用 FontCollection 和 之前创建的 TypographyStyle 创建 TypographyCreate。TypographyCreate 用于创建 Typography
    OH_Drawing_TypographyCreate *handler = OH_Drawing_CreateTypographyHandler(typoStyle, fc);

    // 加入带有可变字体的文本样式
    OH_Drawing_TypographyHandlerPushTextStyle(handler, txtStyleWithVar);
    // 将文本添加到 handler 中
    OH_Drawing_TypographyHandlerAddText(handler, text);
    // 弹出之前创建的 TextStyle
    OH_Drawing_TypographyHandlerPopTextStyle(handler);

    // 后续加入的不带可变字体的文本样式
    OH_Drawing_TypographyHandlerPushTextStyle(handler, txtStyleNoVar);
    // 将文本添加到 handler 中
    OH_Drawing_TypographyHandlerAddText(handler, text);
    // 弹出之前创建的 TextStyle
    OH_Drawing_TypographyHandlerPopTextStyle(handler);

    OH_Drawing_Typography *typography = OH_Drawing_CreateTypography(handler);
    // 设置页面最大宽度
    double maxWidth = width_;
    OH_Drawing_TypographyLayout(typography, maxWidth);
    // 将文本绘制到画布上
    OH_Drawing_TypographyPaint(typography, cCanvas_, 0, DIV_TEN(width_));

    // 释放内存
    OH_Drawing_DestroyTypographyStyle(typoStyle);
    OH_Drawing_DestroyTextStyle(txtStyleWithVar);
    OH_Drawing_DestroyTextStyle(txtStyleNoVar);
    OH_Drawing_DestroyFontCollection(fc);
    OH_Drawing_DestroyTypographyHandler(handler);
    OH_Drawing_DestroyTypography(typography);

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/6d/v3/6ExqjBQZTaWvqgxGLQ_ycw/zh-cn_image_0000002749493360.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=69B1C27ADC1222FE8846EE1F9F5079D3A16AB0FAB47B5ED6C9480614D6BB5A9C)

### 文本阴影

**文本阴影**为文本提供了深度感，使得文本在背景上更具立体感。通常用于提升文本的视觉吸引力或增强可读性，尤其是在色彩对比度较低的场景下。

其中，文本阴影有三个属性，分别为阴影颜色color、阴影基于当前文本的偏移位置offset、阴影半径blurRadius。

使用阴影效果需要在文本样式中设置对应的阴影效果数组，从而在文本绘制时生效。

|接口定义|描述|
|:------------------------------------------------------------------------------------------------------------------------|:---------------|
|OH_Drawing_Point* OH_Drawing_PointCreate(float x, float y)|用于创建一个坐标点对象。|
|OH_Drawing_TextShadow* OH_Drawing_CreateTextShadow(void)|创建指向文本阴影对象的指针。|
|void OH_Drawing_SetTextShadow(OH_Drawing_TextShadow* shadow, uint32_t color, OH_Drawing_Point* offset, double blurRadius)|设置文本阴影对象的参数。|
|void OH_Drawing_TextStyleAddShadow(OH_Drawing_TextStyle* style, const OH_Drawing_TextShadow* shadow)|文本阴影容器中添加文本阴影元素。|
|void OH_Drawing_DestroyTextShadow(OH_Drawing_TextShadow* shadow)|释放被文本阴影对象占据的内存。|

示例及示意效果如下所示：

    // 创建一个 TypographyStyle 创建 Typography 时需要使用
    OH_Drawing_TypographyStyle *typoStyle = OH_Drawing_CreateTypographyStyle();
    // 设置文本对齐方式为居中
    OH_Drawing_SetTypographyTextAlign(typoStyle, TEXT_ALIGN_CENTER);
    // 设置文本内容
    const char *text = "Hello World Drawing\n";

    // 设置文字颜色、大小、字重，不设置 TextStyle 会使用 TypographyStyle 中的默认 TextStyle
    OH_Drawing_TextStyle *txtStyleWithShadow = OH_Drawing_CreateTextStyle();
    OH_Drawing_SetTextStyleColor(txtStyleWithShadow, OH_Drawing_ColorSetArgb(0xFF, 0x00, 0x00, 0x00));
    OH_Drawing_SetTextStyleFontSize(txtStyleWithShadow, DIV_TEN(width_));
    OH_Drawing_SetTextStyleFontWeight(txtStyleWithShadow, FONT_WEIGHT_400);
    // 设置阴影偏移量
    OH_Drawing_Point *offset = OH_Drawing_PointCreate(1, 1);
    OH_Drawing_TextShadow *shadow = OH_Drawing_CreateTextShadow();
    double radius = 10.0;
    // 为 TextShadow 设置样式
    OH_Drawing_SetTextShadow(shadow, OH_Drawing_ColorSetArgb(0xFF, 0x00, 0x00, 0x00), offset, radius);
    // 将 TextShadow 加入 TextStyle
    OH_Drawing_TextStyleAddShadow(txtStyleWithShadow, shadow);

    // 创建一个不带阴影的 TextStyle 用于对比
    OH_Drawing_TextStyle *txtStyleNoShadow = OH_Drawing_CreateTextStyle();
    // 设置文字颜色、大小、字重，不设置 TextStyle 会使用 TypographyStyle 中的默认 TextStyle
    OH_Drawing_SetTextStyleColor(txtStyleNoShadow, OH_Drawing_ColorSetArgb(0xFF, 0x00, 0x00, 0x00));
    OH_Drawing_SetTextStyleFontSize(txtStyleNoShadow, DIV_TEN(width_));
    OH_Drawing_SetTextStyleFontWeight(txtStyleNoShadow, FONT_WEIGHT_400);

    // 创建 FontCollection，FontCollection 用于管理字体匹配逻辑
    OH_Drawing_FontCollection *fc = OH_Drawing_CreateSharedFontCollection();
    // 使用 FontCollection 和 之前创建的 TypographyStyle 创建 TypographyCreate。TypographyCreate 用于创建 Typography
    OH_Drawing_TypographyCreate *handler = OH_Drawing_CreateTypographyHandler(typoStyle, fc);

    // 加入带有阴影的文本样式
    OH_Drawing_TypographyHandlerPushTextStyle(handler, txtStyleWithShadow);
    // 将文本添加到 handler 中
    OH_Drawing_TypographyHandlerAddText(handler, text);

    // 后续加入的不带阴影的文本样式
    OH_Drawing_TypographyHandlerPushTextStyle(handler, txtStyleNoShadow);
    // 将文本添加到 handler 中
    OH_Drawing_TypographyHandlerAddText(handler, text);

    OH_Drawing_Typography *typography = OH_Drawing_CreateTypography(handler);
    // 设置页面最大宽度
    double maxWidth = width_;
    OH_Drawing_TypographyLayout(typography, maxWidth);
    // 将文本绘制到画布上
    OH_Drawing_TypographyPaint(typography, cCanvas_, 0, DIV_TEN(width_));

    // 释放内存
    OH_Drawing_DestroyTypographyStyle(typoStyle);
    OH_Drawing_DestroyTextStyle(txtStyleWithShadow);
    OH_Drawing_PointDestroy(offset);
    OH_Drawing_DestroyTextShadow(shadow);
    OH_Drawing_DestroyTextStyle(txtStyleNoShadow);
    OH_Drawing_DestroyFontCollection(fc);
    OH_Drawing_DestroyTypographyHandler(handler);
    OH_Drawing_DestroyTypography(typography);

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/d5/v3/PwlCdQZYSUyf3cnSaOcbGA/zh-cn_image_0000002779092419.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=74A6B60AD6905D799CF20C2F74023094144F817B84301EF908E3B137B3F1A500)

### 占位符

占位符绘制用于处理文本中占位符符号的渲染。

占位符也是用来实现图文混排的关键，是指在实际图像或内容注册之前，用来预先提供或替代某个位置的视觉元素。

|接口定义|描述|
|:----------------------------------------------------------------------------------------------------------------------|:-----|
|void OH_Drawing_TypographyHandlerAddPlaceholder(OH_Drawing_TypographyCreate* handler, OH_Drawing_PlaceholderSpan* span)|设置占位符。|

示例及示意效果如下所示：

    // 设置页面最大宽度
    double maxWidth = width_;
    // 创建 FontCollection，FontCollection 用于管理字体匹配逻辑
    OH_Drawing_FontCollection *fc = OH_Drawing_CreateSharedFontCollection();

    // 设置文字颜色、大小、字重，不设置 TextStyle 会使用 TypographyStyle 中的默认 TextStyle
    OH_Drawing_TextStyle *txtStyle = OH_Drawing_CreateTextStyle();
    OH_Drawing_SetTextStyleColor(txtStyle, OH_Drawing_ColorSetArgb(0xFF, 0x00, 0x00, 0x00));
    OH_Drawing_SetTextStyleFontSize(txtStyle, DIV_TEN(width_));
    OH_Drawing_SetTextStyleFontWeight(txtStyle, FONT_WEIGHT_400);

    // 设置文本内容
    const char *text = "Hello World Drawing\n";

    // 创建一个 TypographyStyle 创建 Typography 时需要使用
    OH_Drawing_TypographyStyle *typoStyle = OH_Drawing_CreateTypographyStyle();
    // 设置文本对齐方式为居中
    OH_Drawing_SetTypographyTextAlign(typoStyle, TEXT_ALIGN_CENTER);

    // 使用 FontCollection 和 之前创建的 TypographyStyle 创建 TypographyCreate。TypographyCreate 用于创建 Typography
    OH_Drawing_TypographyCreate *handlerWithPlaceholder = OH_Drawing_CreateTypographyHandler(typoStyle, fc);
    // 创建一个 placeholder，并且初始化其成员变量
    OH_Drawing_PlaceholderSpan placeholder;
    placeholder.width = DIV_TEN(width_);
    placeholder.height = DIV_FIVE(width_);
    placeholder.alignment = ALIGNMENT_ABOVE_BASELINE; // 基线对齐策略
    placeholder.baseline = TEXT_BASELINE_ALPHABETIC;  // 使用的文本基线类型
    placeholder.baselineOffset = 0.0; // 相比基线的偏移量。只有对齐策略是 OFFSET_AT_BASELINE 时生效

    // 将 placeholder 放在开头
    OH_Drawing_TypographyHandlerAddPlaceholder(handlerWithPlaceholder, &placeholder);

    // 将之前创建的 TextStyle 加入 handler
    OH_Drawing_TypographyHandlerPushTextStyle(handlerWithPlaceholder, txtStyle);
    // 将文本添加到 handler 中
    OH_Drawing_TypographyHandlerAddText(handlerWithPlaceholder, text);

    OH_Drawing_Typography *typographyWithPlaceholder = OH_Drawing_CreateTypography(handlerWithPlaceholder);
    OH_Drawing_TypographyLayout(typographyWithPlaceholder, maxWidth);
    // 将文本绘制到画布上
    OH_Drawing_TypographyPaint(typographyWithPlaceholder, cCanvas_, 0, DIV_TEN(width_));

    // 创建 OH_Drawing_TypographyCreate
    OH_Drawing_TypographyCreate *handlerNoPlaceholder = OH_Drawing_CreateTypographyHandler(typoStyle, fc);
    // 将之前创建的 TextStyle 加入 handler
    OH_Drawing_TypographyHandlerPushTextStyle(handlerNoPlaceholder, txtStyle);
    // 将文本添加到 handler 中
    OH_Drawing_TypographyHandlerAddText(handlerNoPlaceholder, text);

    OH_Drawing_Typography *typographyNoPlaceholder = OH_Drawing_CreateTypography(handlerNoPlaceholder);

    OH_Drawing_TypographyLayout(typographyNoPlaceholder, maxWidth);
    // 将文本绘制到画布上
    OH_Drawing_TypographyPaint(typographyNoPlaceholder, cCanvas_, 0, DIV_TWO(width_));

    // 释放内存
    OH_Drawing_DestroyFontCollection(fc);
    OH_Drawing_DestroyTextStyle(txtStyle);
    OH_Drawing_DestroyTypographyStyle(typoStyle);
    OH_Drawing_DestroyTypographyHandler(handlerWithPlaceholder);
    OH_Drawing_DestroyTypographyHandler(handlerNoPlaceholder);
    OH_Drawing_DestroyTypography(typographyWithPlaceholder);
    OH_Drawing_DestroyTypography(typographyNoPlaceholder);

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/ff/v3/7wOxVlN7SxCYfK0YVLiDJg/zh-cn_image_0000002778932561.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=9E0CCBFCC7EBF014C332F1AD013CD0AE473FE9C9D2F190DEF835B0D748032B6D)

### 自动间距

使能自动间距，则会在文本排版时自动调整CJK（中文字符、日文字符、韩文字符）与西文（拉丁字母、西里尔字母、希腊字母）、CJK与数字、CJK与版权符号、版权符号与数字、版权符号与西文之间的间距。例如，在中英文混排场景中，使能自动间距即可在中英文切换的地方自动添加额外间距，提升阅读体验。

|接口定义|描述|
|:--------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------|
|void OH_Drawing_SetTypographyTextAutoSpace(OH_Drawing_TypographyStyle *style, bool enableAutoSpace)|设置文本排版时是否使能自动间距。默认不使能自动间距，一旦使能则会自动调整CJK（中文字符、日文字符、韩文字符）与西文（拉丁字母、西里尔字母、希腊字母）、CJK与数字、CJK与版权符号、版权符号与数字、版权符号与西文之间的间距。|

示例及示意效果如下所示：

    // 创建一个TypographyStyle创建Typography时需要使用
    OH_Drawing_TypographyStyle *typoStyle = OH_Drawing_CreateTypographyStyle();
    // 设置使能自动间距，默认为false
    OH_Drawing_SetTypographyTextAutoSpace(typoStyle, true);
    // 设置文字内容
    const char *text = "test测试©test©测。";

    OH_Drawing_TextStyle *txtStyle = OH_Drawing_CreateTextStyle();
    // 设置文字颜色、大小、字重，不设置TextStyle会使用TypographyStyle中的默认TextStyle
    OH_Drawing_SetTextStyleColor(txtStyle, OH_Drawing_ColorSetArgb(0xFF, 0x00, 0x00, 0x00));
    OH_Drawing_SetTextStyleFontSize(txtStyle, DIV_TEN(width_));

    // 创建FontCollection，FontCollection用于管理字体匹配逻辑
    OH_Drawing_FontCollection *fc = OH_Drawing_CreateSharedFontCollection();
    // 使用FontCollection和之前创建的TypographyStyle创建TypographyCreate。TypographyCreate用于创建Typography
    OH_Drawing_TypographyCreate *handler = OH_Drawing_CreateTypographyHandler(typoStyle, fc);

    // 将文本样式添加到handler中
    OH_Drawing_TypographyHandlerPushTextStyle(handler, txtStyle);
    // 将文本添加到handler中
    OH_Drawing_TypographyHandlerAddText(handler, text);
    // 创建段落
    OH_Drawing_Typography *typography = OH_Drawing_CreateTypography(handler);
    // 设置页面最大宽度
    double maxWidth = width_;
    // 将段落按照排版宽度进行排版
    OH_Drawing_TypographyLayout(typography, maxWidth);
    // 将文本绘制到画布上
    OH_Drawing_TypographyPaint(typography, cCanvas_, 0, DIV_TEN(width_));

    // 设置使能自动间距，用于对比
    OH_Drawing_SetTypographyTextAutoSpace(typoStyle, false);

    // 使用FontCollection和之前创建的TypographyStyle创建TypographyCreate。TypographyCreate用于创建Typography
    OH_Drawing_TypographyCreate *handlerWithoutAutoSpace = OH_Drawing_CreateTypographyHandler(typoStyle, fc);

    // 将文本样式添加到handlerWithoutAutoSpace中
    OH_Drawing_TypographyHandlerPushTextStyle(handlerWithoutAutoSpace, txtStyle);
    // 将文本添加到handlerWithoutAutoSpace中
    OH_Drawing_TypographyHandlerAddText(handlerWithoutAutoSpace, text);
    // 创建段落
    OH_Drawing_Typography *typographyWithoutAutoSpace = OH_Drawing_CreateTypography(handlerWithoutAutoSpace);
    // 将段落按照排版宽度进行排版
    OH_Drawing_TypographyLayout(typographyWithoutAutoSpace, maxWidth);
    // 将文本绘制到画布上
    OH_Drawing_TypographyPaint(typographyWithoutAutoSpace, cCanvas_, 0, DIV_FOUR(width_));

    // 释放内存
    OH_Drawing_DestroyTypographyStyle(typoStyle);
    OH_Drawing_DestroyTextStyle(txtStyle);
    OH_Drawing_DestroyFontCollection(fc);
    OH_Drawing_DestroyTypographyHandler(handler);
    OH_Drawing_DestroyTypographyHandler(handlerWithoutAutoSpace);
    OH_Drawing_DestroyTypography(typography);
    OH_Drawing_DestroyTypography(typographyWithoutAutoSpace);

|段落样式设置（自动间距）|示意效果|
|:-----------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|不使能自动间距|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/08/v3/yehDctUnTj-A2HKMKqCuUQ/zh-cn_image_0000002749333480.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=4E36EBE58A71073BFCDEAA5ED884BEB97009B3E7F4CF09A74C47CA237BB39121)|
|使能自动间距|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/69/v3/m3HclEuARlSk-59wW8SBVQ/zh-cn_image_0000002749493362.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=0CC69DBB93ACEC42DB0D6FCA87F7B838B5B9B7E081F4CB1CD4F06F3D865545D6)|

### 渐变色

**渐变色** 是一种在文字设计中广泛应用的视觉效果，通过在文字的不同部分应用不同的颜色，从而创造出从一种颜色平滑过渡到另一种颜色的效果。可以通过着色器实现文字渐变的效果，着色器的更多介绍请参考[着色器效果](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/complex-drawing-effect-c#着色器效果)。

|接口定义|描述|
|:----------------------------------------------------------------------------------------------------------|:----------------------|
|void OH_Drawing_SetTextStyleForegroundBrush(OH_Drawing_TextStyle* style, OH_Drawing_Brush* foregroundBrush)|添加前景画刷，渐变着色器属性依附于前景画刷中。|

示例及效果如下所示：

    OH_Drawing_TypographyStyle *typoStyle = OH_Drawing_CreateTypographyStyle();
    OH_Drawing_TextStyle *txtStyle = OH_Drawing_CreateTextStyle();
    // 设置文字大小
    OH_Drawing_SetTextStyleFontSize(txtStyle, DIV_TEN(width_));
    // 创建着色器对象，并设置颜色、变化起始点与结束点
    OH_Drawing_Point *startPt = OH_Drawing_PointCreate(0, 0);
    // 结束点位于(900, 900)
    OH_Drawing_Point *endPt = OH_Drawing_PointCreate(900, 900);
    uint32_t colors[] = {0xFFFFFF00, 0xFFFF0000, 0xFF0000FF};
    float pos[] = {0.0f, 0.5f, 1.0f};
    // pos数组长度为3
    OH_Drawing_ShaderEffect *colorShaderEffect =
        OH_Drawing_ShaderEffectCreateLinearGradient(startPt, endPt, colors, pos, 3, OH_Drawing_TileMode::CLAMP);
    // 创建画刷对象,并将着色器添加到画刷
    OH_Drawing_Brush *brush = OH_Drawing_BrushCreate();
    OH_Drawing_BrushSetShaderEffect(brush, colorShaderEffect);
    // 将画刷添加到文本样式中
    OH_Drawing_SetTextStyleForegroundBrush(txtStyle, brush);
    // 创建排版对象，并绘制
    OH_Drawing_FontCollection *fc = OH_Drawing_CreateSharedFontCollection();
    OH_Drawing_TypographyCreate *handler = OH_Drawing_CreateTypographyHandler(typoStyle, fc);
    OH_Drawing_TypographyHandlerPushTextStyle(handler, txtStyle);
    const char *text = "Hello World";
    OH_Drawing_TypographyHandlerAddText(handler, text);
    OH_Drawing_Typography *typography = OH_Drawing_CreateTypography(handler);
    // 设置页面最大宽度
    double maxWidth = width_;
    // 将段落按照排版宽度进行排版
    OH_Drawing_TypographyLayout(typography, maxWidth);
    OH_Drawing_TypographyPaint(typography, cCanvas_, 0, DIV_TEN(width_));

    // 释放对象
    OH_Drawing_PointDestroy(startPt);
    OH_Drawing_PointDestroy(endPt);
    OH_Drawing_DestroyFontCollection(fc);
    OH_Drawing_ShaderEffectDestroy(colorShaderEffect);
    OH_Drawing_BrushDestroy(brush);
    OH_Drawing_DestroyTextStyle(txtStyle);
    OH_Drawing_DestroyTypographyStyle(typoStyle);
    OH_Drawing_DestroyTypographyHandler(handler);
    OH_Drawing_DestroyTypography(typography);

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/f8/v3/1i0uGo2ZQ_GEwgAIeHkMOQ/zh-cn_image_0000002779092421.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=DE68E3D9E5F536102A7FF29482300796C7134F5996957B9D05ABA7AC6F32F42F)

### 垂直对齐

**垂直对齐**用于调整文本在一行中垂直方向的排版位置。开启行高缩放或行内存在不同字号文本混排时使能垂直对齐，可以让文本实现顶部对齐、居中对齐、底部对齐或基线对齐（默认）。

|接口定义|描述|
|:------------------------------------------------------------------------------------------------------------------------|:------------|
|void OH_Drawing_SetTypographyVerticalAlignment(OH_Drawing_TypographyStyle* style, OH_Drawing_TextVerticalAlignment align)|设置文本垂直方向排版方式。|

示例及效果如下所示：

    OH_Drawing_TypographyStyle *typoStyle = OH_Drawing_CreateTypographyStyle();
    OH_Drawing_TextStyle *txtStyle = OH_Drawing_CreateTextStyle();
    // 设置垂直对齐方式
    OH_Drawing_SetTypographyVerticalAlignment(typoStyle,
                                              OH_Drawing_TextVerticalAlignment::TEXT_VERTICAL_ALIGNMENT_CENTER);
    // 设置文字大小
    OH_Drawing_SetTextStyleFontSize(txtStyle, DIV_TEN(width_));
    // 设置文字颜色
    OH_Drawing_SetTextStyleColor(txtStyle, OH_Drawing_ColorSetArgb(0xFF, 0x00, 0x00, 0x00));
    // 创建排版对象，并绘制
    OH_Drawing_FontCollection *fc = OH_Drawing_CreateSharedFontCollection();
    OH_Drawing_TypographyCreate *handler = OH_Drawing_CreateTypographyHandler(typoStyle, fc);
    OH_Drawing_TypographyHandlerPushTextStyle(handler, txtStyle);
    const char *text = "VerticalAlignment-center";
    OH_Drawing_TypographyHandlerAddText(handler, text);
    OH_Drawing_Typography *typography = OH_Drawing_CreateTypography(handler);
    // 设置页面最大宽度
    double maxWidth = width_;
    // 将段落按照排版宽度进行排版
    OH_Drawing_TypographyLayout(typography, maxWidth);
    OH_Drawing_TypographyPaint(typography, cCanvas_, 0, DIV_TEN(width_));

    // 释放对象
    OH_Drawing_DestroyFontCollection(fc);
    OH_Drawing_DestroyTextStyle(txtStyle);
    OH_Drawing_DestroyTypographyStyle(typoStyle);
    OH_Drawing_DestroyTypographyHandler(handler);
    OH_Drawing_DestroyTypography(typography);

效果如下（黑框仅为展示文本绘制区域，实际不绘制）：

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/4c/v3/RsXVLf8-TZuZ3SHDL6YAlQ/zh-cn_image_0000002749333462.jpg?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=1FE75CAD7CBBD6DB0296EED1D3238294DB520BF1437645078F1C1932CC01279E)

### 上下标

**上下标**能将文本作为上标或下标参与排版。一般用于数学公式、化学式等场景。

|接口定义|描述|
|:---------------------------------------------------------------------------------------------------------|:-------|
|void OH_Drawing_SetTextStyleBadgeType(OH_Drawing_TextStyle* style, OH_Drawing_TextBadgeType textBadgeType)|使能上下标样式。|

示例及效果如下所示：

    OH_Drawing_TypographyStyle *typoStyle = OH_Drawing_CreateTypographyStyle();
    OH_Drawing_TextStyle *txtStyle = OH_Drawing_CreateTextStyle();
    OH_Drawing_TextStyle *badgeTxtStyle = OH_Drawing_CreateTextStyle();
    // 设置文字大小
    OH_Drawing_SetTextStyleFontSize(txtStyle, DIV_TWENTY(width_));
    OH_Drawing_SetTextStyleFontSize(badgeTxtStyle, DIV_TWENTY(width_));
    // 设置文字颜色
    OH_Drawing_SetTextStyleColor(txtStyle, OH_Drawing_ColorSetArgb(0xFF, 0x00, 0x00, 0x00));
    OH_Drawing_SetTextStyleColor(badgeTxtStyle, OH_Drawing_ColorSetArgb(0xFF, 0x00, 0x00, 0x00));
    // 使能文本上标
    OH_Drawing_SetTextStyleBadgeType(badgeTxtStyle, OH_Drawing_TextBadgeType::TEXT_SUPERSCRIPT);
    // 创建排版对象，并绘制
    OH_Drawing_FontCollection *fc = OH_Drawing_CreateSharedFontCollection();
    OH_Drawing_TypographyCreate *handler = OH_Drawing_CreateTypographyHandler(typoStyle, fc);
    OH_Drawing_TypographyHandlerPushTextStyle(handler, txtStyle);
    const char *text = "Mass-energy equivalence: E=mc";
    OH_Drawing_TypographyHandlerAddText(handler, text);
    OH_Drawing_TypographyHandlerPushTextStyle(handler, badgeTxtStyle);
    const char *badgeText = "2";
    OH_Drawing_TypographyHandlerAddText(handler, badgeText);
    OH_Drawing_Typography *typography = OH_Drawing_CreateTypography(handler);
    // 设置页面最大宽度
    double maxWidth = width_;
    // 将段落按照排版宽度进行排版
    OH_Drawing_TypographyLayout(typography, maxWidth);
    OH_Drawing_TypographyPaint(typography, cCanvas_, 0, DIV_TEN(width_));

    // 释放对象
    OH_Drawing_DestroyFontCollection(fc);
    OH_Drawing_DestroyTextStyle(txtStyle);
    OH_Drawing_DestroyTextStyle(badgeTxtStyle);
    OH_Drawing_DestroyTypographyStyle(typoStyle);
    OH_Drawing_DestroyTypographyHandler(handler);
    OH_Drawing_DestroyTypography(typography);

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/0a/v3/xTn_EcabQeCi0s1yqLK-uQ/zh-cn_image_0000002779092403.jpg?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=3EF25DDFEBB9EE21BD1FDDD198018503FE3B4D2C2248B9A32807B2FA72CE13F0)

### 高对比度

高对比度可将深色文字变黑、浅色文字变白。开发者可选择开启或关闭应用的高对比度文字渲染，或遵循系统设置中的高对比度文字配置。

|接口定义|描述|
|:----------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|void OH_Drawing_SetTextHighContrast(OH_Drawing_TextHighContrast action)|设置文字渲染高对比度模式。模式具体可参考[OH_Drawing_TextHighContrast](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-drawing-text-global-h#oh_drawing_texthighcontrast)。|

示例及示意效果如下所示：

    // 开启APP的文字渲染高对比模式，该模式的优先级要高于系统设置中的高对比度文字配置
    OH_Drawing_SetTextHighContrast(TEXT_APP_ENABLE_HIGH_CONTRAST);
    // 创建一个 TypographyStyle，创建 Typography 时需要使用
    OH_Drawing_TypographyStyle *typoStyle = OH_Drawing_CreateTypographyStyle();

    // 设置文字颜色、大小，不设置 TextStyle 会使用 TypographyStyle 中的默认 TextStyle
    OH_Drawing_TextStyle *txtStyle = OH_Drawing_CreateTextStyle();
    OH_Drawing_SetTextStyleColor(txtStyle, OH_Drawing_ColorSetArgb(0xFF, 0x6F, 0xFF, 0xFF));
    OH_Drawing_SetTextStyleFontSize(txtStyle, DIV_TEN(width_));

    // 创建 FontCollection，FontCollection 用于管理字体匹配逻辑
    OH_Drawing_FontCollection *fc = OH_Drawing_CreateSharedFontCollection();
    // 使用 FontCollection 和 之前创建的 TypographyStyle 创建 TypographyCreate
    OH_Drawing_TypographyCreate *handler = OH_Drawing_CreateTypographyHandler(typoStyle, fc);

    // 将之前创建的 TextStyle 加入 handler 中
    OH_Drawing_TypographyHandlerPushTextStyle(handler, txtStyle);
    // 设置文本内容，并将文本添加到 handler 中
    const char *text = "Hello World Drawing\n";
    OH_Drawing_TypographyHandlerAddText(handler, text);

    OH_Drawing_Typography *typography = OH_Drawing_CreateTypography(handler);
    // 设置页面最大宽度
    double maxWidth = width_;
    // 将段落按照排版宽度进行排版
    OH_Drawing_TypographyLayout(typography, maxWidth);
    // 将文本绘制到画布上
    OH_Drawing_TypographyPaint(typography, cCanvas_, 0, DIV_TEN(width_));

    // 释放内存
    OH_Drawing_DestroyTypographyStyle(typoStyle);
    OH_Drawing_DestroyTextStyle(txtStyle);
    OH_Drawing_DestroyFontCollection(fc);
    OH_Drawing_DestroyTypographyHandler(handler);
    OH_Drawing_DestroyTypography(typography);

|高对比度设置|示意效果|
|:------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|不开启高对比度|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/06/v3/xfDaubWUQLKyoocNTohvnA/zh-cn_image_0000002778932563.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=EEDA943A1B504B9F0F178DC8E85D656F597366C0BEFD63CE6EA7B3413021A113)|
|开启高对比度|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/cf/v3/Wox7g6kaTqamJignN3VF8g/zh-cn_image_0000002749333482.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=E26B6313B45A561A82360A6BDD7CBA71AE465B13C6D1AFE6DD2B9287265521D3)|

### 行高调整

调整行高可以改变文本行的垂直间距，行间距将变得更松散或更紧凑，可以显著改善文本垂直方向截断问题，使文本更易读。

当前行高调整方式包括两种：设置行高上限/下限和使用行高缩放系数。

**行高调整（方式一）**

从API version 21开始，支持为文本行设置行高上限与下限。

|接口定义|描述|
|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------|
|[OH_Drawing_ErrorCode OH_Drawing_SetTextStyleAttributeDouble(OH_Drawing_TextStyle* style, OH_Drawing_TextStyleAttributeId id, double value)](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-drawing-text-typography-h#oh_drawing_settextstyleattributedouble)|传入id为OH_Drawing_TextStyleAttributeId::TEXT_STYLE_ATTR_D_LINE_HEIGHT_MAXIMUM，设置行高上限。|
|[OH_Drawing_ErrorCode OH_Drawing_SetTextStyleAttributeDouble(OH_Drawing_TextStyle* style, OH_Drawing_TextStyleAttributeId id, double value)](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-drawing-text-typography-h#oh_drawing_settextstyleattributedouble)|传入id为OH_Drawing_TextStyleAttributeId::TEXT_STYLE_ATTR_D_LINE_HEIGHT_MINIMUM，设置行高下限。|

示例及效果如下所示：

    OH_Drawing_TypographyStyle *typoStyle = OH_Drawing_CreateTypographyStyle();
    OH_Drawing_TextStyle *txtStyle = OH_Drawing_CreateTextStyle();
    // 设置文字大小为50
    OH_Drawing_SetTextStyleFontSize(txtStyle, 50);
    // 设置文字颜色
    OH_Drawing_SetTextStyleColor(txtStyle, OH_Drawing_ColorSetArgb(0xFF, 0x00, 0x00, 0x00));
    OH_Drawing_SetTextStyleAttributeDouble(txtStyle,
        OH_Drawing_TextStyleAttributeId::TEXT_STYLE_ATTR_D_LINE_HEIGHT_MAXIMUM, 65); // 设置行高上限为65
    OH_Drawing_SetTextStyleAttributeDouble(txtStyle,
        OH_Drawing_TextStyleAttributeId::TEXT_STYLE_ATTR_D_LINE_HEIGHT_MINIMUM, 65); // 设置行高下限为65
    // 创建排版对象，并绘制
    OH_Drawing_FontCollection *fc = OH_Drawing_CreateSharedFontCollection();
    OH_Drawing_TypographyCreate *handler = OH_Drawing_CreateTypographyHandler(typoStyle, fc);
    OH_Drawing_TypographyHandlerPushTextStyle(handler, txtStyle);
    const char *text = "Hello World!";
    OH_Drawing_TypographyHandlerAddText(handler, text);
    OH_Drawing_Typography *typography = OH_Drawing_CreateTypography(handler);
    // 排版宽度为1000
    OH_Drawing_TypographyLayout(typography, 1000);
    OH_Drawing_TypographyPaint(typography, cCanvas_, 0, 0);

    // 释放对象
    OH_Drawing_DestroyFontCollection(fc);
    OH_Drawing_DestroyTextStyle(txtStyle);
    OH_Drawing_DestroyTypographyStyle(typoStyle);
    OH_Drawing_DestroyTypographyHandler(handler);
    OH_Drawing_DestroyTypography(typography);

具体效果如下所示：

|行高上限值|行高下限值|示意效果（黑框仅为展示文本绘制区域，实际不绘制）|
|:----|:----|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|65|65|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/f/v3/9Pdp3ttrQKaKCEmvTygLMA/zh-cn_image_0000002779092405.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=ADC27391D4D15EB8B2A346E5FF54DFD5AB46A9D02C317C973733264D4BE06D23)|
|200|200|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/6e/v3/hqUgLEoMRUipc1cRMrGTDg/zh-cn_image_0000002778932547.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=791857A294CA05675C36D3A38FE1952A4FC25F6471E459C831C6CF18B8917780)|

**行高调整（方式二）**

设置行高缩放系数。

|接口定义|描述|
|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------|
|[void OH_Drawing_SetTextStyleFontHeight(OH_Drawing_TextStyle* style, double fontHeight)](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-drawing-text-typography-h#oh_drawing_settextstylefontheight)|使能行高缩放。|
|[OH_Drawing_ErrorCode OH_Drawing_SetTextStyleAttributeInt(OH_Drawing_TextStyle* style, OH_Drawing_TextStyleAttributeId id, int value)](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-drawing-text-typography-h#oh_drawing_settextstyleattributeint)|传入id为OH_Drawing_TextStyleAttributeId::TEXT_STYLE_ATTR_I_LINE_HEIGHT_STYLE，使能行高缩放样式。|

示例及效果如下所示：

    OH_Drawing_TypographyStyle *typoStyle = OH_Drawing_CreateTypographyStyle();
    OH_Drawing_TextStyle *txtStyle = OH_Drawing_CreateTextStyle();
    // 设置文字大小为50
    OH_Drawing_SetTextStyleFontSize(txtStyle, 50);
    // 设置文字颜色
    OH_Drawing_SetTextStyleColor(txtStyle, OH_Drawing_ColorSetArgb(0xFF, 0x00, 0x00, 0x00));
    // 设置行高缩放系数为1.5
    OH_Drawing_SetTextStyleFontHeight(txtStyle, 1.5);
    // 设置行高缩放样式（1代表行高缩放以字形高度作为缩放基数）
    OH_Drawing_SetTextStyleAttributeInt(txtStyle,
        OH_Drawing_TextStyleAttributeId::TEXT_STYLE_ATTR_I_LINE_HEIGHT_STYLE, 1);
    // 创建排版对象，并绘制
    OH_Drawing_FontCollection *fc = OH_Drawing_CreateSharedFontCollection();
    OH_Drawing_TypographyCreate *handler = OH_Drawing_CreateTypographyHandler(typoStyle, fc);
    OH_Drawing_TypographyHandlerPushTextStyle(handler, txtStyle);
    const char *text = "Hello World!";
    OH_Drawing_TypographyHandlerAddText(handler, text);
    OH_Drawing_Typography *typography = OH_Drawing_CreateTypography(handler);
    // 排版宽度为1000
    OH_Drawing_TypographyLayout(typography, 1000);
    OH_Drawing_TypographyPaint(typography, cCanvas_, 0, 0);

    // 释放对象
    OH_Drawing_DestroyFontCollection(fc);
    OH_Drawing_DestroyTextStyle(txtStyle);
    OH_Drawing_DestroyTypographyStyle(typoStyle);
    OH_Drawing_DestroyTypographyHandler(handler);
    OH_Drawing_DestroyTypography(typography);

具体效果如下所示：

|行高缩放样式|示意效果（黑框仅为展示文本绘制区域，实际不绘制）|
|:------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|TEXT_LINE_HEIGHT_BY_FONT_SIZE|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/a9/v3/x-KYbh2xTzqGuJq8OsEE9w/zh-cn_image_0000002749333466.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=2A1B0BF94E72F58AA3EAB63A39CF7D8ED2A1C6E72F1EB42C14E97B07E9A682C6)|
|TEXT_LINE_HEIGHT_BY_FONT_HEIGHT|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/be/v3/lS3bOESGTeCq6qArJM2BAA/zh-cn_image_0000002749493348.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=48DA4B51361F152AE978ACD6B1E1CA23F5313F2C0CCB4DEEC4E6472947F79DE9)|

### 行间距调整

从API version 21开始，支持设置行间距可以改善文本行之间的距离，提高阅读体验。

|接口定义|描述|
|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------|
|[OH_Drawing_ErrorCode OH_Drawing_SetTypographyStyleAttributeDouble(OH_Drawing_TypographyStyle* style, OH_Drawing_TypographyStyleAttributeId id, double value)](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-drawing-text-typography-h#oh_drawing_settypographystyleattributedouble)|传入id为OH_Drawing_TypographyStyleAttributeId::TYPOGRAPHY_STYLE_ATTR_D_LINE_SPACING，设置行间距。|

示例及效果如下所示：

    OH_Drawing_TypographyStyle *typoStyle = OH_Drawing_CreateTypographyStyle();
    OH_Drawing_SetTypographyStyleAttributeDouble(typoStyle,
        OH_Drawing_TypographyStyleAttributeId::TYPOGRAPHY_STYLE_ATTR_D_LINE_SPACING, 100); // 设置行间距为100
    OH_Drawing_TextStyle *txtStyle = OH_Drawing_CreateTextStyle();
    // 设置文字大小为50
    OH_Drawing_SetTextStyleFontSize(txtStyle, 50);
    // 设置文字颜色
    OH_Drawing_SetTextStyleColor(txtStyle, OH_Drawing_ColorSetArgb(0xFF, 0x00, 0x00, 0x00));
    // 创建排版对象，并绘制
    OH_Drawing_FontCollection *fc = OH_Drawing_CreateSharedFontCollection();
    OH_Drawing_TypographyCreate *handler = OH_Drawing_CreateTypographyHandler(typoStyle, fc);
    OH_Drawing_TypographyHandlerPushTextStyle(handler, txtStyle);
    const char *text = "Hello World!";
    OH_Drawing_TypographyHandlerAddText(handler, text);
    OH_Drawing_Typography *typography = OH_Drawing_CreateTypography(handler);
    // 排版宽度为200
    OH_Drawing_TypographyLayout(typography, 200);
    OH_Drawing_TypographyPaint(typography, cCanvas_, 0, 0);

    // 释放对象
    OH_Drawing_DestroyFontCollection(fc);
    OH_Drawing_DestroyTextStyle(txtStyle);
    OH_Drawing_DestroyTypographyStyle(typoStyle);
    OH_Drawing_DestroyTypographyHandler(handler);
    OH_Drawing_DestroyTypography(typography);

具体效果如下所示：

|行间距|上升部下降部开关|示意效果（黑框仅为展示文本绘制区域，实际不绘制）|
|:--|:----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|0|TEXT_HEIGHT_ALL|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/35/v3/cRiZ5W0HTOuMFqe44sxaAg/zh-cn_image_0000002749493364.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=9B1BC1E40A46CE83B1CEED96C89DF237B20B59D47D29E8C9EC462A426BFA3AC9)|
|100|TEXT_HEIGHT_ALL|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/a6/v3/FlOu1157QyCaGMK2TJia0g/zh-cn_image_0000002778932549.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=8A64B068001E4C8761F9D76E51446B802A5ACA159FEEFC852E5C62BEF5ED974D)|
|100|TEXT_HEIGHT_DISABLE_ALL|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/7f/v3/uVgGQv5oS5ytFJTGh2Zo5A/zh-cn_image_0000002779092407.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=52EAD71CEBF7A98CA48D07C567E51570E761E3741B242934277A893F0E9A55A9)|

### 省略号样式设置

从API version 22开始，支持设置省略号样式，在文本内容超出显示区域时截断文本。从API version 24开始，支持多行省略模式。

使用[OH_Drawing_SetTypographyStyleAttributeInt](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-drawing-text-typography-h#oh_drawing_settypographystyleattributeint)接口，传入[TYPOGRAPHY_STYLE_ATTR_I_ELLIPSIS_MODAL](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-drawing-text-typography-h#oh_drawing_typographystyleattributeid)设置省略号模式，可选的省略号模式可见[OH_Drawing_EllipsisModal](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-drawing-text-typography-h#oh_drawing_ellipsismodal)。

    // 创建一个带有省略号设置的 TypographyStyle
    OH_Drawing_TypographyStyle *typoStyle = OH_Drawing_CreateTypographyStyle();
    // 设置最大行数为2，超过2行的部分将被省略
    OH_Drawing_SetTypographyTextMaxLines(typoStyle, 2);
    // 设置省略号模式为尾部省略
    OH_Drawing_SetTypographyStyleAttributeInt(typoStyle,
        OH_Drawing_TypographyStyleAttributeId::TYPOGRAPHY_STYLE_ATTR_I_ELLIPSIS_MODAL, ELLIPSIS_MODAL_TAIL);
    // 设置自定义省略号字符串
    OH_Drawing_SetTypographyTextEllipsis(typoStyle, "...");

|省略号模式|效果|
|:------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|ELLIPSIS_MODAL_TAIL|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/0e/v3/_-gCUaNeQiKzMxA12wPt1g/zh-cn_image_0000002779092423.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=75A33A52D37E43729354008CAB129B09F8840275E377E6BE31BB9E2D1EDAFCCC)|
|ELLIPSIS_MODAL_HEAD|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/4c/v3/uHtx5QW0Tt60sAe3-unpaA/zh-cn_image_0000002778932565.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=212F03A1293AB9C5E6A851E86D45F985669CC273E283D2234899EA44519751C1)|
|ELLIPSIS_MODAL_MIDDLE|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/45/v3/lxWzpCa1Sr-rJWBw8sJqfQ/zh-cn_image_0000002749333484.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=4FB57C81C71C6B85CAB931768C8305EEBE650FC4CEDE1A2D731F165E26A60728)|
|ELLIPSIS_MODAL_MULTILINE_HEAD|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/3e/v3/NGdSg5qmSBKZndsxLhesNw/zh-cn_image_0000002749493366.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=F47EDD8DB646E6C386EE58577268434BA42671EECAC16EF33C27856839DEB5CC)|
|ELLIPSIS_MODAL_MULTILINE_MIDDLE|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/f4/v3/LX4F5pI-SY6ys5cvKTmDNg/zh-cn_image_0000002779092425.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=E4517CF2A618CBD6CC10923E742F41E475CD803D8A6E0A1EAC450E3388ED7158)|

### 文字换行方式设置

从API version 22开始，支持在文本排版时设置断行策略，断行策略决定了文本如何在行尾进行换行处理。

使用[OH_Drawing_SetTypographyTextBreakStrategy](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-drawing-text-typography-h#oh_drawing_settypographytextbreakstrategy)接口设置断行策略，可选的断行策略可见[OH_Drawing_BreakStrategy](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-drawing-text-typography-h#oh_drawing_breakstrategy)。

    // 创建一个设置了均衡断行策略的 TypographyStyle
    OH_Drawing_TypographyStyle *typoStyle = OH_Drawing_CreateTypographyStyle();
    // 设置断行策略为 BALANCED（均衡策略）
    OH_Drawing_SetTypographyTextBreakStrategy(typoStyle, BREAK_STRATEGY_BALANCED);

|换行方式|效果|
|:-----------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|GREEDY|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/c8/v3/fNlK5NTmQEWqTHmkOCFAGg/zh-cn_image_0000002778932567.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=683A4086CF58025B92CA562881DE5C88012C053600EDDA444F56B2983EDD7599)|
|HIGH_QUALITY|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/ab/v3/MmWPRWqWSKaJXTLL3UhCZg/zh-cn_image_0000002749333486.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=7207D6FAC200792E18FA2C6437DE9A9844EB1D25D66E625A522F14D0088F9C93)|
|BALANCED|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/f4/v3/-7f-jMLgRAidXp5f3hFYwA/zh-cn_image_0000002749493368.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=47EC1BD82888AA88FAA5041432F4E08D8D0389C4FD9E111906B929A17EAF5FBD)|

### 行首标点压缩

从API version 23开始，在文本排版中支持行首标点压缩功能。通过启用行首标点压缩功能，可以将行首标点符号进行挤压处理，提升排版紧凑度。

使用[OH_Drawing_SetTypographyStyleAttributeBool](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-drawing-text-typography-h#oh_drawing_settypographystyleattributebool)接口，传入[TYPOGRAPHY_STYLE_ATTR_B_COMPRESS_HEAD_PUNCTUATION](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-drawing-text-typography-h#oh_drawing_typographystyleattributeid)设置是否启用行首标点压缩，使用[OH_Drawing_GetTypographyStyleAttributeBool](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-drawing-text-typography-h#oh_drawing_gettypographystyleattributebool)接口查询是否启用了行首标点压缩。

    // 第二段：开启行首标点压缩
    OH_Drawing_TypographyStyle *typoStyleCompress = OH_Drawing_CreateTypographyStyle();
    OH_Drawing_SetTypographyTextAlign(typoStyleCompress, TEXT_ALIGN_LEFT);
    OH_Drawing_ErrorCode errorCode = OH_Drawing_SetTypographyStyleAttributeBool(typoStyleCompress,
        OH_Drawing_TypographyStyleAttributeId::TYPOGRAPHY_STYLE_ATTR_B_COMPRESS_HEAD_PUNCTUATION, true);
    if (errorCode != OH_DRAWING_SUCCESS) {
        DRAWING_LOGE("SetTypographyStyleAttributeBool failed, errorCode: %{public}d", errorCode);
    }

|是否开启行首标点压缩|效果|
|:---------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|关闭行首标点压缩|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/dc/v3/Yeh3LlVVT5ilEQcWBro6wA/zh-cn_image_0000002779092427.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=BBA33B375E941A65D2FF2BC6281101E2CA65A3AF0708CBF0358574171FCCB70C)|
|开启行首标点压缩|![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/11/v3/ki3UHKdETsWiSf_2xOv24w/zh-cn_image_0000002778932569.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=49F7C19687869D900AD80D4D31E9ACE3E0D03B106E53E3254C66E75C3D95DDAD)|

## 样式的拷贝、绘制与显示

支持拷贝文本样式、段落样式、阴影样式，以便快速复制相关样式作用到不同文字上。

|接口定义|描述|
|:--------------------------------------------------------------------------------------------|:-----------------------------|
|OH_Drawing_TypographyStyle* OH_Drawing_CopyTypographyStyle(OH_Drawing_TypographyStyle* style)|创建一个段落样式的对象副本，用于拷贝一个已有的段落样式对象。|
|OH_Drawing_TextStyle* OH_Drawing_CopyTextStyle(OH_Drawing_TextStyle* style)|创建一个文本样式的对象副本，用于拷贝一个已有的文本样式对象。|
|OH_Drawing_TextShadow* OH_Drawing_CopyTextShadow(OH_Drawing_TextShadow* shadow)|创建一个文本阴影的对象副本，用于拷贝一个已有的文本阴影对象。|

示例及示意效果如下所示：

    // 创建一个TypographyStyle，其中创建Typography时需要使用
    OH_Drawing_TypographyStyle *typoStyle = OH_Drawing_CreateTypographyStyle();
    // 配置段落样式包括：使能自动间距、最大行数、省略号样式、省略号文本、对齐方式
    // 使能自动间距
    OH_Drawing_SetTypographyTextAutoSpace(typoStyle, true);
    // 设置段落最大行数为3行
    OH_Drawing_SetTypographyTextMaxLines(typoStyle, 3);
    // 设置省略号模式为尾部省略号
    OH_Drawing_SetTypographyStyleAttributeInt(typoStyle, TYPOGRAPHY_STYLE_ATTR_I_ELLIPSIS_MODAL, ELLIPSIS_MODAL_TAIL);
    // 设置省略号文本
    OH_Drawing_SetTypographyTextEllipsis(typoStyle, "...");
    // 设置对齐方式为居中对齐
    OH_Drawing_SetTypographyTextAlign(typoStyle, TEXT_ALIGN_CENTER);

    OH_Drawing_TextStyle *txtStyle = OH_Drawing_CreateTextStyle();
    // 设置文字颜色、大小、字重，不设置TextStyle会使用TypographyStyle中的默认TextStyle
    OH_Drawing_SetTextStyleColor(txtStyle, OH_Drawing_ColorSetArgb(0xFF, 0x00, 0x00, 0x00));
    OH_Drawing_SetTextStyleFontSize(txtStyle, DIV_TEN(width_));
    // 设置文本的装饰线
    // 添加下划线
    OH_Drawing_SetTextStyleDecoration(txtStyle, TEXT_DECORATION_UNDERLINE);
    // 设置装饰线样式为波浪线样式
    OH_Drawing_SetTextStyleDecorationStyle(txtStyle, TEXT_DECORATION_STYLE_WAVY);
    // 设置下划线粗细
    OH_Drawing_SetTextStyleDecorationThicknessScale(txtStyle, 1);
    // 设置下划线颜色为蓝色
    OH_Drawing_SetTextStyleDecorationColor(txtStyle, OH_Drawing_ColorSetArgb(0xFF, 0x00, 0x00, 0xFF));

    // 设置阴影的颜色、偏移量、模糊半径
    // 创建阴影对象
    OH_Drawing_TextShadow *shadow = OH_Drawing_CreateTextShadow();
    // 设置阴影偏移量为(5, 5)
    OH_Drawing_Point *offset = OH_Drawing_PointCreate(5, 5);
    // 定义阴影模糊半径为4
    OH_Drawing_SetTextShadow(shadow, OH_Drawing_ColorSetArgb(0xFF, 0xFF, 0x00, 0xFF), offset, 4);

    // 拷贝阴影对象
    OH_Drawing_TextShadow *shadowCopy = OH_Drawing_CopyTextShadow(shadow);
    // 将拷贝出的阴影添加到文本样式中
    OH_Drawing_TextStyleAddShadow(txtStyle, shadowCopy);

    // 创建FontCollection，FontCollection用于管理字体匹配逻辑
    OH_Drawing_FontCollection *fc = OH_Drawing_CreateSharedFontCollection();

    // 使用FontCollection和之前创建的TypographyStyle创建TypographyCreate。TypographyCreate用于创建Typography
    OH_Drawing_TypographyCreate *handler = OH_Drawing_CreateTypographyHandler(typoStyle, fc);
    // 将段落一文本样式添加到handler中
    OH_Drawing_TypographyHandlerPushTextStyle(handler, txtStyle);
    // 将段落一文本添加到handler中
    const char *text = "The text style, paragraph style, and text shadow of the copied text will be exactly the same "
                       "as those of the original text.";
    OH_Drawing_TypographyHandlerAddText(handler, text);
    // 创建段落一，并将段落一按照排版宽度进行排版
    OH_Drawing_Typography *typography = OH_Drawing_CreateTypography(handler);
    double maxWidth = width_;
    OH_Drawing_TypographyLayout(typography, maxWidth);
    OH_Drawing_TypographyPaint(typography, cCanvas_, 0, DIV_TEN(width_));

    // 生成第二段文本，其中，文本样式和段落样式均由第一段文本拷贝而来
    // 复制文本样式
    OH_Drawing_TextStyle *textStyleCopy = OH_Drawing_CopyTextStyle(txtStyle);
    // 复制段落样式
    OH_Drawing_TypographyStyle *typographyStyleCopy = OH_Drawing_CopyTypographyStyle(typoStyle);

    // 使用复制的样式创建段落二，后续可以观察段落一和段落二是否绘制效果一致
    OH_Drawing_TypographyCreate *handlerCopy = OH_Drawing_CreateTypographyHandler(typographyStyleCopy, fc);
    OH_Drawing_TypographyHandlerPushTextStyle(handlerCopy, textStyleCopy);
    OH_Drawing_TypographyHandlerAddText(handlerCopy, text);
    OH_Drawing_Typography *typographyCopy = OH_Drawing_CreateTypography(handlerCopy);
    OH_Drawing_TypographyLayout(typographyCopy, maxWidth);
    OH_Drawing_TypographyPaint(typographyCopy, cCanvas_, 0, DIV_TWO(width_));

    // 释放内存
    OH_Drawing_DestroyFontCollection(fc);
    OH_Drawing_DestroyTypographyStyle(typoStyle);
    OH_Drawing_DestroyTextStyle(txtStyle);
    OH_Drawing_DestroyTypographyHandler(handler);
    OH_Drawing_DestroyTypography(typography);
    // 拷贝的段落样式也需要释放内存
    OH_Drawing_DestroyTypographyStyle(typographyStyleCopy);
    // 拷贝的文本样式也需要释放内存
    OH_Drawing_DestroyTextStyle(textStyleCopy);
    OH_Drawing_DestroyTypographyHandler(handlerCopy);
    OH_Drawing_DestroyTypography(typographyCopy);
    OH_Drawing_PointDestroy(offset);
    OH_Drawing_DestroyTextShadow(shadow);
    OH_Drawing_DestroyTextShadow(shadowCopy);

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/aa/v3/qaXt-vDvQmifK8xViQa_HA/zh-cn_image_0000002749333488.png?HW-CC-KV=V1&HW-CC-Date=20260929T121647Z&HW-CC-Expire=31536000000&HW-CC-Sign=BB5BAFECF8E358C140AFCA7AB52D327EECFD6F0E3A847DD6BF30661B7D485511)