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