1# 系统字体的信息获取和使用（C/C++） 2 3 4## 场景介绍 5 6系统字体是指操作系统预设的字体，用于在没有指定自定义字体时显示文本，确保文本的可读性和一致性。默认的系统字体为“HarmonyOS Sans”。 7 8**使用系统字体**的情况通常是在应用未注册自定义字体，或在没有显式指定文本样式时，系统会使用默认的系统字体。另外，系统字体有多种，开发者可以先获取系统字体的配置信息，并根据信息中的字体家族名来进行系统字体的切换和使用。 9 10**禁用系统字体**的情况通常发生在开发者希望确保应用中仅使用自定义字体，而不受操作系统默认字体影响的场景。当自定义字体不存在时，不禁用系统字体，系统则会自动回退到默认字体。通过禁用系统字体，开发者可以在任何场景避免字体回退为系统默认字体，确保文本渲染符合设计预期，从而统一应用的视觉风格。 11 12 13## 接口说明 14 15以下是系统字体相关的常用接口和结构体，详细接口说明请参考[Drawing](../reference/apis-arkgraphics2d/_drawing.md)。 16 17| 接口名 | 描述 | 18| -------- | -------- | 19| OH_Drawing_FontConfigInfo\* OH_Drawing_GetSystemFontConfigInfo(OH_Drawing_FontConfigInfoErrorCode\*) | 获取系统字体配置信息，返回系统字体配置信息结构体OH_Drawing_FontConfigInfo。 | 20| void OH_Drawing_DestroySystemFontConfigInfo(OH_Drawing_FontConfigInfo\*) | 释放系统字体配置信息占用的内存。 | 21| OH_Drawing_FontCollection\* OH_Drawing_CreateSharedFontCollection(void) | 创建可共享的字体集对象OH_Drawing_FontCollection。 | 22| OH_Drawing_TextStyle\* OH_Drawing_CreateTextStyle(void) | 创建指向OH_Drawing_TextStyle对象的指针，用于设置文本样式。 | 23| OH_Drawing_SetTextStyleFontFamilies (OH_Drawing_TextStyle \*, int, const char \*fontFamilies[]) | 设置指定文本样式的字体家族类型。 | 24| void OH_Drawing_DisableFontCollectionSystemFont(OH_Drawing_FontCollection\* fontCollection) | 禁用系统字体。 | 25 26| 结构体名 | 描述 | 27| -------- | -------- | 28| OH_Drawing_FontConfigInfo | 系统字体配置信息结构体。 | 29| OH_Drawing_FontGenericInfo | 系统所支持的通用字体集信息结构体。 | 30| OH_Drawing_FontFallbackGroup | 备用字体集信息结构体。 | 31 32 33## 获取系统字体信息 34 351. 导入依赖的相关头文件。 36 37 ```c++ 38 #include <native_drawing/drawing_font_collection.h> 39 #include <native_drawing/drawing_text_typography.h> 40 #include <native_drawing/drawing_register_font.h> 41 #include <hilog/log.h> 42 ``` 43 442. 获取系统字体的配置信息，可以通过返回的状态码确定获取信息是否成功，状态码的包含的具体情况和对应含义可见[OH_Drawing_FontConfigInfoErrorCode](../reference/apis-arkgraphics2d/_drawing.md#oh_drawing_fontconfiginfoerrorcode)。 45 46 ```c++ 47 OH_Drawing_FontConfigInfoErrorCode fontConfigInfoErrorCode; // 用于接收错误代码 48 OH_Drawing_FontConfigInfo* fontConfigInfo = OH_Drawing_GetSystemFontConfigInfo(&fontConfigInfoErrorCode); 49 if(fontConfigInfoErrorCode != SUCCESS_FONT_CONFIG_INFO) { 50 OH_LOG_Print(LOG_APP, LOG_ERROR, LOG_DOMAIN, "DrawingSample", "获取系统信息失败，错误代码为： %{public}d", fontConfigInfoErrorCode); 51 } 52 ``` 53 543. 系统字体的配置信息[OH_Drawing_FontConfigInfo](../reference/apis-arkgraphics2d/_o_h___drawing___font_config_info.md)包含以下几类信息： 55 56 - 系统字体文件路径数量。 57 58 - 通用字体集列表数量。 59 60 - 备用字体集列表数量。 61 62 - 系统字体文件路径列表。 63 64 - 通用字体集列表，具体信息可见[OH_Drawing_FontGenericInfo](../reference/apis-arkgraphics2d/_o_h___drawing___font_generic_info.md)结构体。 65 66 - 备用字体集列表，具体信息可见[OH_Drawing_FontFallbackGroup](../reference/apis-arkgraphics2d/_o_h___drawing___font_fallback_group.md)结构体。 67 68 以下示例展示系统字体的一些具体配置信息的获取： 69 70 ```c++ 71 // 获取系统字体配置信息示例 72 if (fontConfigInfo != nullptr) { 73 // 获取字体文件路径数量，打印日志 74 size_t fontDirCount = fontConfigInfo->fontDirSize; 75 OH_LOG_Print(LOG_APP, LOG_INFO, LOG_DOMAIN, "DrawingSample", "字体文件路径数量为: %{public}zu\n", fontDirCount); 76 // 遍历字体文件路径列表，打印日志 77 for (size_t i = 0; i < fontDirCount; ++i) { 78 OH_LOG_Print(LOG_APP, LOG_INFO, LOG_DOMAIN, "DrawingSample", "字体文件路径为: %{public}s\n", fontConfigInfo->fontDirSet[i]); 79 } 80 // 获取通用字体集数量，打印日志 81 size_t genericCount = fontConfigInfo->fontGenericInfoSize; 82 OH_LOG_Print(LOG_APP, LOG_INFO, LOG_DOMAIN, "DrawingSample", "通用字体集数量为: %{public}zu\n", genericCount); 83 // 遍历获取每个通用字体集中的字体家族名（例如 HarmonyOS Sans），打印日志 84 for(size_t i = 0; i < genericCount; ++i) { 85 OH_Drawing_FontGenericInfo& genericInfo = fontConfigInfo->fontGenericInfoSet[i]; 86 OH_LOG_Print(LOG_APP, LOG_INFO, LOG_DOMAIN, "DrawingSample", "获取第%{public}zu个通用字体集中的字体家族名为: %{public}s", i, genericInfo.familyName); 87 } 88 } 89 ``` 90 91 以下打印的示例为应用设备系统对应的部分系统字体配置信息情况，不同设备系统配置信息可能不同，此处仅示意。 92 93  94 954. 如若后续不再需要系统字体的系统配置信息时，则释放其占用的内存。 96 97 ```c++ 98 OH_Drawing_DestroySystemFontConfigInfo(fontConfigInfo); 99 ``` 100 101 102## 使用或切换系统字体 103 104系统字体可以有多种，可以先获取系统字体配置信息，再根据其中的字体家族名来进行系统字体的切换和使用。 105 106如果不指定使用任何字体时，会使用系统默认字体“HarmonyOS Sans”显示文本。 107 1081. 导入依赖的相关头文件。 109 110 ```c++ 111 #include <native_drawing/drawing_font_collection.h> 112 #include <native_drawing/drawing_text_typography.h> 113 #include <native_drawing/drawing_register_font.h> 114 #include <hilog/log.h> 115 ``` 116 1172. 创建字体管理器，建议优先使用OH_Drawing_CreateSharedFontCollection创建可共享的字体集对象。 118 119 > **说明：** 120 > 121 > 使用OH_Drawing_CreateFontCollection和OH_Drawing_CreateSharedFontCollection均可创建字体管理器OH_Drawing_FontCollection对象，但前者创建的字体集指针对象只能被一个段落生成器OH_Drawing_TypographyCreate对象使用，无法被多个段落生成器OH_Drawing_TypographyCreate对象共享使用。如需在多个段落生成器OH_Drawing_TypographyCreate对象间共享使用，请使用后者创建可共享的字体集对象。 122 123 ```c++ 124 OH_Drawing_FontCollection *fontCollection = OH_Drawing_CreateSharedFontCollection(); 125 ``` 126 1273. 创建一个文本样式对象，即OH_Drawing_TextStyle对象，用于设置文本样式。 128 129 ```c++ 130 OH_Drawing_TextStyle textStyle = OH_Drawing_CreateTextStyle(); 131 ``` 132 1334. [获取系统字体信息](#获取系统字体信息)，取用系统字体的字体家族名，并在文本样式中切换设置为该系统字体。 134 135 ```c++ 136 // 情况一：设置系统字体为"HarmonyOS Sans Condensed" 137 const char* myFontFamilies[] = {"HarmonyOS Sans Condensed"}; 138 OH_Drawing_SetTextStyleFontFamilies(textStyle, 1, myFontFamilies); 139 140 // 情况二：不手动设置，此时使用的是系统默认字体"HarmonyOS Sans" 141 // const char* myFontFamilies[] = {"HarmonyOS Sans Condensed"}; 142 // OH_Drawing_SetTextStyleFontFamilies(textStyle, 1, myFontFamilies); 143 ``` 144 1455. 生成最终段落文本，以便实现最终的文本绘制和显示。 146 147 ```c++ 148 // 设置其他文本样式 149 OH_Drawing_SetTextStyleColor(textStyle , OH_Drawing_ColorSetArgb(0xFF, 0x00, 0x00, 0x00)); 150 OH_Drawing_SetTextStyleFontSize(textStyle , 70.0); 151 // 创建一个段落样式对象，以设置排版风格 152 OH_Drawing_TypographyStyle *typographyStyle = OH_Drawing_CreateTypographyStyle(); 153 OH_Drawing_SetTypographyTextAlign(typographyStyle, TEXT_ALIGN_LEFT); // 设置段落样式为左对齐 154 // 创建一个段落生成器 155 OH_Drawing_TypographyCreate* handler = OH_Drawing_CreateTypographyHandler(typographyStyle, fontCollection); 156 // 在段落生成器中设置文本样式 157 OH_Drawing_TypographyHandlerPushTextStyle(handler, textStyle); 158 // 在段落生成器中设置文本内容 159 const char* text = "Hello World. 你好世界。\n以上文字使用了系统字体"; 160 OH_Drawing_TypographyHandlerAddText(handler, text); 161 // 通过段落生成器生成段落 162 OH_Drawing_Typography* typography = OH_Drawing_CreateTypography(handler); 163 ``` 164 165 166## 禁用系统字体 167 168当自定义字体不存在时，不禁用系统字体，系统则会自动回退到默认字体。通过禁用系统字体，开发者可以在任何场景避免字体回退为系统默认字体，确保文本渲染符合设计预期，从而统一应用的视觉风格。 169 170在一些应用场景中，开发者可能希望只使用自定义字体来确保字体一致性或提供更具个性化的用户体验。此时，开发者可以通过禁用系统字体，确保应用只使用注册的自定义字体，而不依赖于系统字体。 171 172> **说明：** 173> 174> 禁用系统字体后，请确保注册使用自定义字体，否则文本将无法正常显示。 175 1761. 确保已成功注册自定义字体，用于保证禁用系统字体后文本的正常显示，具体可见[自定义字体的注册和使用](custom-font-c.md)。 177 1782. 导入依赖的相关头文件。 179 180 ```c++ 181 #include <native_drawing/drawing_font_collection.h> 182 #include <native_drawing/drawing_text_typography.h> 183 #include <native_drawing/drawing_register_font.h> 184 #include <hilog/log.h> 185 ``` 186 1873. 创建字体管理器，建议优先使用OH_Drawing_CreateSharedFontCollection创建可共享的字体集对象。 188 189 ```c++ 190 OH_Drawing_FontCollection *fontCollection = OH_Drawing_CreateSharedFontCollection(); 191 ``` 192 1934. 禁用系统字体。 194 195 ```c++ 196 OH_Drawing_DisableFontCollectionSystemFont(fontCollection); 197 ``` 198 1995. 创建文本样式对象，使用注册成功的自定义字体。 200 201 > **注意：** 202 > 203 > 若不设置字体，文本会默认使用系统字体，而系统字体禁用后若不设置使用自定义字体，文本将无法正常显示。 204 205 ```c++ 206 OH_Drawing_TextStyle textStyle = OH_Drawing_CreateTextStyle(); 207 // 禁用系统字体后的几种情况如下： 208 // 情况一：如果此时设置使用了自定义字体，文本会正常显示 209 const char* myFontFamilies[] = {"myFamilyName"}; //确保已成功注册自定义字体，填入自定义字体的字体家族名 210 OH_Drawing_SetTextStyleFontFamilies(textStyle, 1, myFontFamilies); 211 212 // 情况二：如果此时使用了系统字体，文本将无法显示 213 const char* myFontFamilies[] = {"HarmonyOS_Sans"}; 214 OH_Drawing_SetTextStyleFontFamilies(textStyle, 1, myFontFamilies); 215 216 // 情况三：如果此时不设置使用字体，文本会默认使用系统默认字体，而此时系统字体已被禁用，因此文本将无法显示 217 const char* myFontFamilies[] = {"HarmonyOS_Sans"}; 218 // OH_Drawing_SetTextStyleFontFamilies(textStyle, 1, myFontFamilies); 219 ``` 220 2216. 生成最终的段落文本，以便实现最终的文本绘制和显示。 222 223 ```c++ 224 // 设置其他文本样式 225 OH_Drawing_SetTextStyleColor(textStyle , OH_Drawing_ColorSetArgb(0xFF, 0x00, 0x00, 0x00)); 226 OH_Drawing_SetTextStyleFontSize(textStyle , 70.0); 227 // 创建一个段落样式对象，以设置排版风格 228 OH_Drawing_TypographyStyle *typographyStyle = OH_Drawing_CreateTypographyStyle(); 229 OH_Drawing_SetTypographyTextAlign(typographyStyle, TEXT_ALIGN_LEFT); // 设置段落样式为左对齐 230 // 创建一个段落生成器 231 OH_Drawing_TypographyCreate* handler = OH_Drawing_CreateTypographyHandler(typographyStyle, fontCollection); 232 // 在段落生成器中设置文本样式 233 OH_Drawing_TypographyHandlerPushTextStyle(handler, textStyle); 234 // 在段落生成器中设置文本内容 235 const char* text = "Hello World. 你好世界。\n以上文字使用了主题字体"; 236 OH_Drawing_TypographyHandlerAddText(handler, text); 237 // 通过段落生成器生成段落 238 OH_Drawing_Typography* typography = OH_Drawing_CreateTypography(handler); 239 ``` 240
