c++如何将数据导出为PDF文档_libharu库基础用法【进阶】

先说几个关键点。libharu 这个库在生成 PDF 这件事上确实很轻量，但坑也不少，尤其是跟中文、表格、内存打交道的时候。下面几个问题可以说是高频故障区，提前摸透了，能省不少排查时间。

libharu 生成 PDF 时中文乱码或文字不显示

中文乱码的根源在于，libharu 默认只认 Latin-1 字符集，压根不内置中文字体。你直接塞 UTF-8 的中文字符串进去，它要么跳过，要么显示成空白。

那问题出在哪？解决方案其实很明确：必须手动加载 TrueType 字体（比如 simsun.ttc 或 NotoSansCJKsc-Regular.otf），同时调用 HPDF_UseUTFEncoding() 切换编码模式。注意，这个调用顺序很关键，必须在加载任何字体之前执行。

HPDF_Doc doc = HPDF_New(NULL, NULL);
HPDF_UseUTFEncoding(doc);  // 必须在加载字体前调用
HPDF_Font font = HPDF_LoadTTFontFromFile(doc, "simsun.ttc", HPDF_TRUE);
HPDF_Page page = HPDF_AddPage(doc);
HPDF_Page_SetFontAndSize(page, font, 12);

几个容易踩的细节：

• HPDF_UseUTFEncoding() 如果调用晚了，那就白费力气，不会生效。
• Windows 下路径写反斜杠要记得转义（比如 "C:\\fonts\\simsun.ttc"），或者干脆改用正斜杠省事。
• 字体文件必须包含完整的 CJK 字形，光靠一个纯英文的 arial.ttf 是没办法显示中文的。
• macOS/Linux 上还要留意字体路径的权限问题，不然 HPDF_INVALID_FONT 错误随时会找上门。

用 libharu 绘制表格时行列对齐错乱

libharu 没有原生的表格 API，只能靠手动画线加填内容。这个操作本身不复杂，但坐标系理解稍有偏差，结果就是错位。

实操中，有几个关键点值得注意：

• 坐标系原点在页面左下角（0, 0），Y 轴向上增长，千万别和 GUI 坐标搞混了。
• 文本垂直对齐的问题在于，HPDF_Page_TextOut() 定位的是基线（baseline），不是文字顶部。想让文字在单元格里居中，Y 值需要减去字体高度的约 0.8 倍。
• 列宽别靠猜，要用 HPDF_Font_GetTextWidth() 实际测量，中英文宽度差异很大，按字符数估算肯定会跑偏。
• 画线之后别忘了调用 HPDF_Page_Stroke()，否则线条不会出现。

举个简单的两列表头实现：

float x1 = 50, x2 = 300, y = 750;
HPDF_Page_MoveTo(page, x1, y); HPDF_Page_LineTo(page, x2, y);
HPDF_Page_MoveTo(page, x1, y - 20); HPDF_Page_LineTo(page, x2, y - 20);
HPDF_Page_Stroke(page);
HPDF_Page_TextOut(page, x1 + 5, y - 15, "序号");   // y-15 是基线位置
HPDF_Page_TextOut(page, x1 + 100, y - 15, "姓名");

导出大量数据时内存暴涨或崩溃

libharu 的 HPDF_Doc 对象会缓存所有绘图指令和字体资源。如果逐行写入数据时不释放中间对象，内存很快就撑不住了。尤其是循环里反复调用 HPDF_AddPage() 或者每次加载新字体，OOM 几乎是必然的。

对此，基本的解决思路是：

• 复用同一个 HPDF_Font 对象，不要每页都重新加载字体文件。
• 单页内容超过 50 行就考虑分页，用 HPDF_Page_GetHeight() 动态判断剩余空间，避免单页内容过大。
• 导出完成后立刻调用 HPDF_Free()，它会释放所有关联内存——这一步遗漏是内存泄漏最常见的原因。
• 调试阶段可以用 HPDF_SetPagesConfiguration(doc, 10) 限制初始页槽，提前暴露分配问题。

libharu 在 C++ 中处理异常与错误码

libharu 是纯 C 库，不抛 C++ 异常。所有错误都通过返回码和回调函数传递，默认情况下是静默失败，很容易掩盖问题。

正确的做法是主动设置错误回调，并检查关键函数的返回值：

• 注册回调：用 HPDF_SetErrorHandler(doc, error_handler)，自定义函数接收 HPDF_STATUS 和 HPDF_UINT 错误码。
• 关键函数如 HPDF_LoadTTFontFromFile()、HPDF_Sa veToFile() 返回 HPDF_OK 才算成功，否则需要查 HPDF_GetError() 定位问题。
• 常见错误码：HPDF_INVALID_FONT（字体加载失败）、HPDF_PAGE_OUT_OF_RANGE（页索引越界）、HPDF_FILE_IO_ERROR（写磁盘失败）。
• 如果用 C++ RAII 封装，记得在析构函数里确保 HPDF_Free() 被调用，防止资源残留。

导出 PDF 从来不是“调个函数就完事”那么简单。字体路径、坐标系理解、内存生命周期、错误反馈链，每个环节都有陷阱。最容易被忽略的，其实是错误回调注册和 HPDF_UseUTFEncoding() 的调用顺序——这两个地方不落实，中文导出大概率无声无息地失败。