字体

FAQ1 支持哪些类型的字体？ 如何enable/disable？

Solution 主要支持 FreeType TTF 字体和 bitmap 点阵字体，也可以在特定配置下支持 OTF 字体。

常见选型建议如下：

客户需求	建议方案	注意事项
多语言、字号多、文本内容动态变化	FreeType TTF	适合消息、设置项、电子书、动态文本等场景
固定文本、固定字号、追求显示速度	静态 bitmap	字形预先生成，显示速度快，但字号和字符集合固定
已经有 LVGL 原生 bitmap 字体资源	LVGL 原生 bitmap	按 LVGL 字体转换工具生成并接入
需要从多语言表批量抽取静态点阵字	Font_gen 静态 bitmap	适合产品静态文案、多语言资源和性能优化
需要粗体、斜体或 transform	FreeType Normal	需要选择 FREETYPE_NORMAL_FONT
需要印度语系、泰语、阿语等复杂脚本变形	FreeType + HarfBuzz	需要打开 PKG_USING_HARFBUZZ，并确认字体包含 GSUB/GPOS
需要 OTF 字体	FreeType Normal + OTF 支持	需要打开 FREETYPE_SUPPORT_OTF，并满足 cache 配置要求

相关配置入口在 menuconfig → Font Config：

• LV_USING_FREETYPE_ENGINE：使能 FreeType 字体引擎。

• LV_USING_EXTERNAL_FREETYPE_ENGINE：使用完整 FreeType 后端。

• FREETYPE_TINY_FONT：使用压缩 TTF 方案，资源更省，但能力受限。

• FREETYPE_NORMAL_FONT：使用完整 FreeType Normal 方案，支持更完整的字体能力。

• USING_BITMAP_FONT：使能 bitmap 点阵字体。

• FREETYPE_SUPPORT_OTF：在 FREETYPE_NORMAL_FONT 下支持 OTF 字体。

OTF 说明： 默认客户优先使用 TTF。如果确实需要加载 .otf 字体，需要选择 FREETYPE_NORMAL_FONT，打开 FREETYPE_SUPPORT_OTF，并确认 FT_CACHE_SIZE 满足配置依赖。OTF 会增加 cache 和内存压力，建议只在确认字体资源确实需要 OTF 时打开。

---

FAQ2 是否支持多个ttf？

Solution支持多个ttf的组合。字体显示时，会根据solution\examples\watch\resource\fonts\freetype\ttf_order.txt中的顺序进行查找。

---

FAQ3 如何从一个ttf中抽取自己需要的字以及如何把多一个ttf合为一个ttf？

可以使用fontCreater的工具编辑实现。

---

FAQ4 如何增删一个ttf的字体？

1. 在具体产品工程的 resource/fonts/freetype 目录下（例如 solution/examples/watch/resource/fonts/freetype）增删字体，参见ttf字体增删

2. 点击Butterfli的刷新图标，对应的字体将在界面上显示

3. 在Butterfli的界面上选择使用哪些字体

---

FAQ5 如何在代码中动态调整ttf字体的访问顺序？

1. ttf_order.txt规定了ttf字体默认的顺序。开机后将以该顺序默认进行访问

2. 可通过代码中重新设置字体顺序进行设置

3. 设置完成后可通过Finsh命令font_list查看顺序

---

FAQ6 如何临时修改某个字体支持的字号？

参见重新设置某个字体支持的字号。使用场景是某个页面需要一个不在默认中的字号，进入这个页面修改，退出页面恢复，从而能减少字号的数量。

1. 临时修改某个字体的字号：lvsf_set_font_size_by_name

2. 重置某个字体的字号，恢复到默认字号：lvsf_reset_font_size_by_name

---

FAQ7 如何修改默认支持的字号？

参见ttf字号设置。

1. 直接修改lvsf_font.h中FONT_SIZES的宏定义。该种方式适用于所有产品平台都是用一组字号的情况

2. 通过menuconfig打开FT_SIZE_SELF_DEFINED，然后在产品工程的 HCPU 和 Simulator 目录下定义__applicaiton_private__/ft_size_custom_reg.h来实现。该方式适用于某个产品工程使用一套独立字号的情况。

---

FAQ8 如何在代码中使用ttf的字体？

参见代码中使用ttf字体。

1. 自动选择字体： lv_ext_set_local_font

2. 使用指定字体： lv_ext_label_set_indicated_font

3. 通过menuconfig打开FT_SIZE_SELF_DEFINED，然后在产品工程的 HCPU 和 Simulator 目录下定义__applicaiton_private__/ft_size_custom_reg.h来实现。该方式适用于某个产品工程使用一套独立字号的情况。

---

FAQ9 如何临时使用某个ttf的字体？

参见引用外置ttf字体。

1. 使用lvsf_font_load_ex加载指定的字体

2. 使用lvsf_font_set_enable启用/禁用字体

3. 使用lv_ext_label_set_indicated_font使用已经使能的字体

4. 使用lvsf_font_unload_ex卸载lvsf_font_load_ex装入的字体

---

适用场景：某个应用需要特殊的字体，如阅读器或悬浮歌词应用等。

---

FAQ10 如何在文本中使用emoji？

参见emoji字体增删。

1. 通过menuconfig → Font Config → use emoji使能 emoji。

2. 在具体产品工程的 resource\images_emoji\common\ezip 目录下（例如 solution\examples\watch\resource\images_emoji\common\ezip）增删需要支持的 emoji 图标，并按照要求命名文件名

3. 在lv_label_set_text中text参数中包括emoji时，文本将显示emoji的图标

---

FAQ11 某个字在字库中找不到时，会怎样？

某个字在字库中找不到时，会使用 .notdef 字形，显示 “豆腐块”□，提示无对应字形。如果需要修改显示方式，可以参考该章节

---

FAQ12 如何使用bitmap的字体？

bitmap 字体在 Solution 里有两条路径，客户可以按需求选择：

LVGL 原生 bitmap 字体

这是 LVGL 自带的标准方式：先用 LVGL 的字体转换工具生成 bitmap 字体 .c 文件，再按 Solution 工程资源方式接入。

适用场景：

• 已经有 LVGL 原生的 bitmap 字体资源；

• 只想把少量固定字号做成静态点阵，不依赖 Solution 的字体抽取工具；

• 工程里需要和 LVGL 原生资源流程保持一致。

使用步骤：

1. 通过 menuconfig → Font Config 使能 bitmap 能力。

2. 使用 LVGL 官网字体转换工具 生成 bitmap 字体 .c 文件。

3. 将生成的字体 .c 文件放入工程的 resource/fonts/bitmap 目录，例如 solution/examples/watch/resource/fonts/bitmap。

4. 在代码中使用 lv_ext_set_local_bitmap_font 将该 bitmap 字体应用到控件上。

Solution 的 Font_gen 静态 bitmap 字体

这是 Solution 新增的字体工具链。它可以根据 multi_language_table.xlsx 中的文本和字号信息，从指定 TTF 中抽取字符并生成静态 bitmap 字体，用于提升固定文案的显示速度。

适用场景：

• 需要从统一的多语言表中批量抽取静态文案；

• 需要把部分常用文本做成静态 bitmap，以提升显示速度；

• 希望和 Solution 的字体资源组织方式保持一致。

使用前提：

1. multi_language_table.xlsx 中需要填写 Bitmap_fontsize 列，用来说明每条文本对应的 bitmap 字号。

2. 需要提供用于渲染的 TTF 字体。位图模式默认主要使用第一个 TTF 作为渲染源。

3. 不建议使用 tiny55_full.ttf 或 hindi.ttf 作为静态字体抽取源。

生成示例：

font_gen.exe multi_language_table.xlsx HarmonyOS_Sans_SC_Bold.ttf -i unicode 0x02-0x7F -ttf2bitmap 2

生成结果通常包括：

• static_font_<size>.c：按字号生成的 bitmap 字体文件。

• static_font_header.h：生成字体的头文件。

• static_font_info.h：生成字体的信息文件。

使用步骤：

1. 先在 menuconfig → Font Config 中使能 bitmap 相关能力。

2. 按 Font_gen 文档生成静态 bitmap 字体文件。

3. 将 solution/framework/__template__/project 下的 __applicaiton_private__ 复制到工程 project 目录下。

4. 将生成的 static_font_<size>.c 等文件复制到工程的 project/__applicaiton_private__/ 目录。

5. 在代码中使用 lv_ext_set_local_bitmap_font 应用该 bitmap 字体。

说明： 无论采用哪种方式，bitmap 字体本质上都是静态点阵字形；区别在于生成工具链不同：

• LVGL 原生方式：由 LVGL 工具直接生成；

• Solution 方式：由 Font_gen 从多语言表和 TTF 抽取生成，并按 Solution 的静态字体流程接入。

客户选型建议： 如果只是接入已有 LVGL bitmap 字体，走 LVGL 原生方式；如果要从产品多语言文案中批量生成静态点阵字，优先使用 Font_gen。

参考文档：

• solution/tools/Font_gen/readme.md：查看 font_gen.exe 的参数和输出规则。

• 字体说明：查看 bitmap 字体配置和工程接入方式。

---

FAQ13 ttf字体显示如何支持4bpp或8bpp？

FreeType 字体渲染的 bpp 由 sdk/middleware/lvgl/lv_conf_sifli.h 中的 FT_BPP 控制。

代码中支持的取值包括 1、2、4、8，但实际能否使用还受芯片和 EPIC 渲染格式限制：

1. SF32LB55X、SF32LB56X、SF32LB58X 默认使用 4bpp。

2. 其他系列默认使用 2bpp。

3. 当启用 COMPATIBLE_WITH_SIFLI_EPIC_Ax 时，只支持 2bpp 和 4bpp。

4. 当启用 FT_USING_2BPP_INTERNAL 时，只支持 2bpp、4bpp、8bpp。

5. 1bpp 主要适合软件渲染路径，硬件 EPIC 路径不一定支持。

客户调整时建议按下面顺序处理：

1. 先确认芯片系列和当前工程默认 FT_BPP。

2. 如果只是希望提高字体边缘效果，优先从 2bpp 调到 4bpp 验证。

3. 如果要使用 8bpp，需要同时验证 EPIC 渲染、字体 cache、内存占用和显示效果。

4. 不建议只改 FT_BPP 后直接量产，需要在目标屏幕、目标芯片和目标语言下做完整 UI 回归。

FT_BPP 越高，字体抗锯齿效果通常越好，但字体 bitmap 和 cache 占用也会增加。

---

FAQ14 FreeType 字体是否支持粗体或斜体？

支持，但需要注意版本和配置限制：Solution V2.6 之后的版本才支持 FreeType 字体的粗体、斜体以及 transform 能力。

使用前需要确认：

1. 工程已使能 FreeType。

2. 字体渲染类型选择 FREETYPE_NORMAL_FONT。

3. 如果使用的是 Solution V2.6 之前的版本，则不支持该能力，需要升级到 V2.6 之后版本。

FREETYPE_NORMAL_FONT 与 FREETYPE_TINY_FONT 属于同一组 FreeType 后端选择，不能同时选择。如果原工程依赖 FREETYPE_TINY_FONT 或压缩 TTF 方案，切换到 FREETYPE_NORMAL_FONT 后需要同步验证字体资源、cache、内存和显示效果。

其中，粗体 / 斜体属于 style 能力，transform 属于字体变换能力。两类能力的区别如下：

能力	作用	常见接口	说明
style	设置粗体、斜体等字体样式	lv_ext_label_set_indicated_font_with_style、lv_ext_obj_set_freetype_style	适合做标题加粗、重点文字加粗、斜体等效果
transform	设置字体变换矩阵	lv_ext_label_set_indicated_font_with_transform、lv_ext_obj_set_freetype_transform	可用于缩放、倾斜等变换效果

注意事项：

• style / transform 都是 FreeType 字体能力，不适用于普通 bitmap 字体。

• 如果没有选择 FREETYPE_NORMAL_FONT，粗体 / 斜体等效果不生效。

• transform 属于字体渲染变换能力，效果越复杂，渲染开销越高，性能敏感页面需要实际验证。

• 详细接口说明参见FreeType style 和 transform。

---

FAQ15 FreeType 支持哪些多语言变形（shape）？

Solution V2.6.0 及以后版本支持通过 PKG_USING_HARFBUZZ 打开的多语言变形（shape）能力。当前已适配的语种如下：

文字系统	已适配语种	Language
Devanagari	印地语、马拉地语、尼泊尔语	Hindi, Marathi, Nepali
Bengali	孟加拉语、阿萨姆语	Bengali, Assamese
Gurmukhi	旁遮普语	Punjabi
Gujarati	古吉拉特语	Gujarati
Oriya/Odia	奥里亚语	Odia
Tamil	泰米尔语	Tamil
Telugu	泰卢固语	Telugu
Kannada	卡纳达语	Kannada
Malayalam	马拉雅拉姆语	Malayalam
Sinhala	僧伽罗语	Sinhala
Thai	泰语	Thai
Lao	老挝语	Lao
Khmer	高棉语	Khmer
Myanmar	缅甸语	Burmese
Tibetan	藏语	Tibetan
Mongolian	蒙古语	Mongolian
Arabic	阿拉伯语、波斯语、乌尔都语	Arabic, Persian/Farsi, Urdu
Hebrew	希伯来语	Hebrew
Syriac	叙利亚语	Syriac

注意事项：

• 该能力需要使能 LV_USING_FREETYPE_ENGINE，并打开 PKG_USING_HARFBUZZ。

• USE_HARFBUZZ_HINDI_SHAPER 为隐藏自动项，依赖满足后会默认开启。

• 字体本身还需要包含对应语种的 glyph 以及 GSUB/GPOS 等 OpenType 数据。

• 打开 HarfBuzz 后 code size 约增加 850KB，客户需要提前评估 flash 空间。

• HarfBuzz 解决的是字符 shaping 和 glyph 定位问题，不会自动补齐字体中缺失的字形或 OpenType 表。

• Arabic、Hebrew、Syriac 等 RTL 语言需要重点验证方向、换行、截断、省略号和控件对齐。

• 印度语系、泰语、老挝语、高棉语、缅甸语等需要重点验证元音重排、上下标、连字和组合符号位置。

• 如果需要支持其他需要 shape 的语言，需要客户自行提供支持变形算法及对应 .ttf 方案。