c++如何将数据导出为PDF文档_libharu库基础用法【进阶】
使用libharu库导出PDF时，中文乱码需手动加载TrueType字体并先调用HPDF_UseUTFEncoding()；表格绘制注意坐标系原点在左下角，文本基线对齐；大量数据导出需复用字体对象、及时分页并调用HPDF_Free()释放内存；错误处理应设置回调函数并检查返回值。
先说几个关键点。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() 的调用顺序——这两个地方不落实，中文导出大概率无声无息地失败。
Photoshop 2026 是 Adobe 推出的专业图像处理与视觉设计软件，支持 Windows、macOS 和 iPad 等平台，广泛应用于摄影修图、电商设计、平面海报、数字绘画及视觉合成等创作场景。
Blender 是一款免费开源、跨平台的专业 3D 创作软件，集建模、动画、渲染、视频编辑与视觉合成等功能于一体，广泛应用于影视动画、游戏设计和建筑可视化等领域。软件支持 Cycles 物理渲染器与 Eevee 实时渲染引擎，并提供多边形建模、骨骼绑定、物理模拟等专业工具。Blender 兼容 Windows、macOS 和 Linux 系统，安装包轻巧、运行流畅，依托活跃的全球开发者社区持续更新，是从初学者到专业创作者都值得选择的正版 3D 创作工具。
极度公式是一款跨平台专业LaTeX公式识别编辑软件，支持OCR公式识别和多平台编辑。和使用说明，避免使用，享受完整功能与稳定支持。做扫描整理、文字提取和表格转换时，它能把识别后的处理步骤接得更顺，资料录入这类场景会省下不少时间。
一款文字处理软件，一种订阅式的跨平台办公软件，基于云平台提供多种服务，通过将 Excel 和 Outlook 等应用与 OneDrive 和 Microsoft Teams 等强大的云服务相结合，Office 365 可让任何人使用任何设备随时随地创建和共享内容。
CodeExpander 是一款快捷短语输入增强工具，通过键入缩写自动展开为自定义文段，提升工作效率。任务管理和过程控制会更完整，持续下载、批量同步或需要稳定传输流程的场景会更适合它。
Mountain Duck 是一款能将多个网盘挂载到本地的工具，像本地磁盘一样使用网盘。清理链路的完整性会更好一些，做应用卸载、残留处理和空间整理时，通常能少走很多手动排查步骤。
Photoshop 2026 是 Adobe 推出的专业图像处理与视觉设计软件，支持 Windows、macOS 和 iPad 等平台，广泛应用于摄影修图、电商设计、平面海报、数字绘画及视觉合成等创作场景。
Blender 是一款免费开源、跨平台的专业 3D 创作软件，集建模、动画、渲染、视频编辑与视觉合成等功能于一体，广泛应用于影视动画、游戏设计和建筑可视化等领域。软件支持 Cycles 物理渲染器与 Eevee 实时渲染引擎，并提供多边形建模、骨骼绑定、物理模拟等专业工具。Blender 兼容 Windows、macOS 和 Linux 系统，安装包轻巧、运行流畅，依托活跃的全球开发者社区持续更新，是从初学者到专业创作者都值得选择的正版 3D 创作工具。
极度公式是一款跨平台专业LaTeX公式识别编辑软件，支持OCR公式识别和多平台编辑。和使用说明，避免使用，享受完整功能与稳定支持。做扫描整理、文字提取和表格转换时，它能把识别后的处理步骤接得更顺，资料录入这类场景会省下不少时间。
一款文字处理软件，一种订阅式的跨平台办公软件，基于云平台提供多种服务，通过将 Excel 和 Outlook 等应用与 OneDrive 和 Microsoft Teams 等强大的云服务相结合，Office 365 可让任何人使用任何设备随时随地创建和共享内容。
Wise Folder Hider Pro 是一款专业级文件和文件夹隐藏加密软件，为私密数据添加多重保护。高频操作更强调就近处理，浏览、整理和跨目录移动文件时，来回切换和重复点击都会少很多。
CodeExpander 是一款快捷短语输入增强工具，通过键入缩写自动展开为自定义文段，提升工作效率。任务管理和过程控制会更完整，持续下载、批量同步或需要稳定传输流程的场景会更适合它。