如何使用libharu将UTF-8中文写入PDF？error_no=1028报错排查

在Debian Linux下使用libharu生成含中文的PDF，源代码字符串为UTF-8编码，指定SimSun字体时出现错误：

ERROR: error_no=1028, detail_no=0

改用Helvetica字体无报错，但因该字体无中文字符，PDF无法显示中文。

问题代码 #

#include <stdio.h>
#include <setjmp.h>
#include "hpdf.h"

jmp_buf env;

void error_handler (HPDF_STATUS   error_no,
               HPDF_STATUS   detail_no,
               void         *user_data)
{
    printf ("ERROR: error_no=%04X, detail_no=%u\n", (HPDF_UINT)error_no, (HPDF_UINT)detail_no);
    longjmp(env, 1);
}

int main (int argc, char **argv)
{
    HPDF_Doc pdf = HPDF_New (error_handler, NULL);
    if (!pdf) {
        printf ("error: cannot create PdfDoc object\n");
        return 1;
    }

    if (setjmp(env)) {
        HPDF_Free (pdf);
        return 1;
    }

    HPDF_UseUTFEncodings(pdf);
    HPDF_SetCurrentEncoder(pdf, "UTF-8");
    HPDF_UseCNSFonts (pdf);
    HPDF_Page page = HPDF_AddPage (pdf);

    HPDF_REAL height = HPDF_Page_GetHeight (page);
    HPDF_REAL width = HPDF_Page_GetWidth (page);

    HPDF_Font def_font = HPDF_GetFont (pdf, "SimSun", NULL);
    //HPDF_Font def_font = HPDF_GetFont (pdf, "Helvetica", NULL);
    HPDF_Page_SetFontAndSize (page, def_font, 24);

    //const char* text = "Hello World!";
    const char* text = "Hello: 警告：温度控制已禁用。";
    HPDF_REAL tw = HPDF_Page_TextWidth (page, text);
    HPDF_Page_BeginText (page);
    HPDF_Page_TextOut (page, (width - tw) / 2, height - 50, text);
    HPDF_Page_EndText (page);

    HPDF_SaveToFile (pdf, "a.out.pdf");
    HPDF_Free (pdf);

    return 0;
}

解决方案 #

错误码1028对应HPDF_FONT_NOT_FOUND，核心原因是libharu无法定位到SimSun字体文件，按以下步骤修复：

• 直接加载本地字体文件
  libharu默认不包含SimSun字体，需通过HPDF_LoadTTFontFromFile加载系统中实际存在的字体文件，替换原代码中HPDF_GetFont的调用：

  // 示例：加载系统中的SimSun字体（路径需根据实际情况调整）
  HPDF_Font def_font = HPDF_LoadTTFontFromFile(pdf, "/usr/share/fonts/truetype/simsun/SimSun.ttc", HPDF_TRUE);
  if (!def_font) {
      fprintf(stderr, "Failed to load SimSun font\n");
      longjmp(env, 1);
  }
  

  若系统无SimSun，可改用自带中文字体，比如文泉驿微米黑：

  HPDF_Font def_font = HPDF_LoadTTFontFromFile(pdf, "/usr/share/fonts/truetype/wqy/wqy-microhei.ttc", HPDF_TRUE);
  

• 确保编码设置顺序正确
  原代码中HPDF_UseUTFEncodings和HPDF_SetCurrentEncoder的调用顺序正确，需保持在加载字体之前执行。

• 编译时正确链接库
  编译命令需链接libharu：

  gcc -o pdf_chinese your_code.c -lharu
  

内容的提问来源于stack exchange，提问作者Stefan Koch