鸿蒙Qt字体实战：消灭“豆腐块“乱码与自定义字体加载

原创于 2025-11-23 18:17:23 发布 · 341 阅读

6 ·

CC 4.0 BY-SA版权

文章标签：

#harmonyos #qt #华为

1. 满屏的"豆腐块"

在将Qt应用移植到鸿蒙初期，我们经常遇到一个尴尬的问题：
英文字符显示正常，但中文字符全部变成了方框（俗称"豆腐块" / Tofu）。

或者，设计师提供的精美 ttf 字体，在代码里加载成功了，但界面上死活不显示。

2. 原因一：系统字体回退失败

Qt依赖 fontconfig 或底层系统的字体API来查找默认字体。
在鸿蒙精简版（Standard System）或某些开发板上，可能预装的字体有限，或者Qt无法自动映射到系统的HarmonyOS Sans。

临时方案：
在代码中显式指定一个存在的字体家族。

QApplication app(argc, argv);
QFont font = app.font();
font.setFamily("HarmonyOS Sans SC"); // 尝试系统默认字体名
app.setFont(font);

3. 原因二：自定义字体加载路径错误

更多情况是应用自带了字体文件（如 OpenSans.ttf），但加载失败。

错误代码：

int id = QFontDatabase::addApplicationFont(":/fonts/OpenSans.ttf"); // qrc路径
if (id == -1) {
    qWarning() << "Failed to load font"; // 鸿蒙上这里可能返回-1
}

虽然Qt通常支持从qrc加载字体，但在某些嵌入式或移动平台配置下，Qt需要一个物理文件路径来创建FreeType引擎的句柄。

解决方案：拷贝+加载

策略与Rawfile资源类似，先将字体文件拷贝到沙箱可写目录，再加载。

QString fontPath = copyRawFileToSandbox("myfont.ttf");
int id = QFontDatabase::addApplicationFont(fontPath);

if (id != -1) {
    QString family = QFontDatabase::applicationFontFamilies(id).at(0);
    QFont font(family);
    app.setFont(font);
}

4. 进阶：Qt Quick 中文字体失效

在QML中，你可能设置了：

Text {
    font.family: "MyCustomFont"
    text: "你好"
}

但显示依然是默认字体。

这通常是因为 FontLoader 的使用方式不对。

正确姿势：

FontLoader {
    id: localFont
    source: "file:///data/storage/.../myfont.ttf" // 使用绝对路径
}

Text {
    font.family: localFont.name // 必须引用FontLoader的name属性
    text: "Hello"
}

最佳实践：
尽量使用 qrc:/ 加载 QML 中的字体资源，如果遇到平台兼容性问题（FreeType报错），再回退到本地文件方案。

5. 字体渲染模糊？High DPI适配

如果字体加载出来了，但是边缘锯齿严重或者模糊。
检查 main.cpp 是否开启了High DPI支持。

// Qt 6 默认开启，但在某些鸿蒙设备上可能获取的DPR不对
app.setAttribute(Qt::AA_UseHighDpiPixmaps);

// 手动强制DPR（如果系统识别错误）
qputenv("QT_SCALE_FACTOR", "2");

6. 总结

中文乱码：通常是系统字体映射失败，建议打包开源的中文字体（如 Source Han Sans 的精简版）随App发布。
加载失败：addApplicationFont 对 qrc 支持不稳定时，拷贝到临时目录再加载。
QML字体：使用 FontLoader 并正确引用 .name 属性。

字体是UI的门面，解决好字体问题，应用的质感瞬间提升一个档次。