PDFlib 中文輸出實戰（四）：深入解析 PDFlib 的文本輸入格式與編碼處理

前言

在使用 PDFlib 生成包含中文的 PDF 文件時，正確處理文本輸入格式是關鍵環節。PDFlib 通過 textformat 參數控制字符串的解析方式，支援多種編碼格式，滿足不同程式語言與平台的需求。本文將系統梳理 PDFlib 接收的各種文本輸入形式，並透過實際 C 語言範例展示如何在簡體中文 Windows 環境下正確輸出中文。

PDFlib 支援的文本輸入格式

textformat 參數的有效值如下表所示：

Unicode-capable 與 non-Unicode-capable 語言的差異

PDFlib 依程式語言是否原生支援 Unicode 字串，分為兩類：

• Unicode-capable：COM、.NET、Java、REALbasic、Tcl 等，預設 textformat=utf16。
• non-Unicode-capable：C、C++、Cobol、Perl、PHP、Python、RPG 等，預設 textformat=auto。

對於 non-Unicode-capable 語言，auto 通常能正確處理大多數文本字串；而 Unicode-capable 語言則建議顯式指定 utf16 或 utf8 以避免歧義。

字符引用（Character Reference）機制

啟用 charref=true 並設定 textformat=bytes 後，PDFlib 支援 SGML/HTML 風格的字符引用，可直接在字串中插入特殊字符：

PDF_set_parameter(p, "charref", "true");
PDF_set_parameter(p, "textformat", "bytes");

常用引用範例：

• ­ / ­ / ­：軟連字符
• € / € / €：歐元符號
• <、>、&：<、>、&
• Α：希臘字母 Alpha

完整 C 語言範例：多種 textformat 輸出簡體中文

下列程式碼展示在簡體中文 Windows 下，使用不同 textformat 與編碼組合輸出「簡體中文」四字。程式定義了 8 位元與 16 位元兩組測試案例，涵蓋 bytes、auto、utf16、utf16be、utf16le、utf8 及帶 BOM 的變體，並使用 STSong-Light 字體配合 UniGB-UCS2-H 編碼輸出中文。

/*******************************************************************/
/* This example demostrates output Chinese Simplified text with different */
/* 'textformat' option under Chinese Simplifed Windows. */
/*******************************************************************/
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "pdflib.h"

int main(void) {
    PDF *p = NULL;
    int Font_E = 0, Font_H = 0, Font_CS = 0, Left = 50, y = 800, i = 0;
    const int INCRY = 25;
    char text[128], buf[128];

    /* 1 byte text (English: "Simplified Chinese") */
    static const char byte_text[] = "\123\151\155\160\154\151\146\151\145\144\040\103\150\151\156\145\163\145";
    static const int byte_len = 18;
    static const char byte2_text[] = {0x53,0x69,0x6D,0x70,0x6C,0x69,0x66,0x69,0x65, 0x64,0x20,0x43,0x68,0x69,0x6E,0x65,0x73,0x65};
    static const int byte2_len = 18;

    /* 2 byte text (Simplified Chinese) */
    static const unsigned short utf16_text[] = {0x7B80,0x4F53,0x4E2D,0x6587};
    static const int utf16_len = 8;
    static const unsigned char utf16be_text[] = "\173\200\117\123\116\055\145\207";
    static const int utf16be_len = 8;
    static const unsigned char utf16be_bom_text[] = "\376\377\173\200\117\123\116\055\145\207";
    static const int utf16be_bom_len = 10;
    static const unsigned char utf16le_text[] = "\200\173\123\117\055\116\207\145";
    static const int utf16le_len = 8;
    static const unsigned char utf16le_bom_text[] = "\377\376\200\173\123\117\055\116\207\145";
    static const int utf16le_bom_len = 10;
    static const unsigned char utf8_text[] = "\347\256\200\344\275\223\344\270\255\346\226\207";
    static const int utf8_len = 12;
    static const unsigned char utf8_bom_text[] = "\xEF\xBB\xBF\xE7\xAE\x80\xE4\xBD\x93\xE4\xB8\xAD\xE6\x96\x87";
    static const int utf8_bom_len = 15;
    static const char htmlutf16_text[] = "簡體中文";
    static const int htmlutf16_len = sizeof(htmlutf16_text) - 1;

    typedef struct {
        char *textformat;
        char *encname;
        const char *textstring;
        const int *textlength;
        const char *bomkind;
    } TestCase;

    static const TestCase table_8[] = {
        { "bytes", "winansi", (const char *)byte_text, &byte_len, ""},
        { "auto", "winansi", (const char *)byte_text, &byte_len, ""},
        { "bytes", "winansi", (const char *)byte2_text, &byte2_len, ""},
    };

    static const TestCase table_16[] = {
        { "auto", "unicode", (const char *)utf16_text, &utf16_len, ""},
        { "utf16", "unicode", (const char *)utf16_text, &utf16_len, ""},
        { "auto", "unicode", (const char *)utf16be_bom_text, &utf16be_bom_len, ", UTF-16+BE-BOM"},
        { "auto", "unicode", (const char *)utf16le_bom_text, &utf16le_bom_len, ", UTF-16+LE-BOM"},
        { "utf16be", "unicode", (const char *)utf16be_text, &utf16be_len, ""},
        { "utf16le", "unicode", (const char *)utf16le_text, &utf16le_len, ""},
        { "utf8", "unicode", (const char *)utf8_text, &utf8_len, ""},
        { "auto", "unicode", (const char *)utf8_bom_text, &utf8_bom_len, ", UTF-8+BOM"},
        { "bytes", "unicode", (const char *)htmlutf16_text, &htmlutf16_len, ", HTML unicode character"},
    };

    const int tsize_8 = sizeof table_8 / sizeof (TestCase);
    const int tsize_16 = sizeof table_16 / sizeof (TestCase);

    /* create a new PDFlib object */
    if ((p = PDF_new()) == (PDF *) 0) {
        printf("Couldn't create PDFlib object (out of memory)!\n");
        return(2);
    }

    PDF_TRY(p) {
        if (PDF_begin_document(p, "pdflib_cs4.pdf", 0, "") == -1) {
            printf("Error: %s\n", PDF_get_errmsg(p));
            return(2);
        }
        PDF_set_info(p, "Creator", "pdflib_cs4.c");
        PDF_set_info(p, "Author", "myi@pdflib.com");
        PDF_set_info(p, "Title", "Output Chinese Simplify with Different textformat");

        /* Start a new page. */
        PDF_begin_page_ext(p, a4_width, a4_height, "");
        Font_H = PDF_load_font(p, "Helvetica-Bold", 0, "winansi", "");
        /* 8-bit encoding */
        Font_E = PDF_load_font(p, "Times", 0, "winansi", "");
        PDF_setfont(p, Font_H, 24);
        PDF_show_xy(p, "8-bit encoding", Left+40, y);
        y -= 2*INCRY;
        for (i = 0; i < tsize_8; ++i) {
            PDF_setfont(p, Font_H, 14);
            sprintf(text, "%s encoding, %s textformat %s: ", table_8[i].encname, table_8[i].textformat, table_8[i].bomkind);
            PDF_show_xy(p, text, Left, y);
            y -= INCRY;
            PDF_set_parameter(p, "textformat", table_8[i].textformat);
            PDF_setfont(p, Font_E, 14);
            PDF_show_xy(p, table_8[i].textstring, Left, y);
            y -= INCRY;
        }

        /* 16-bit encoding */
        PDF_setfont(p, Font_H, 24);
        y -= 2*INCRY;
        PDF_show_xy(p, "16-bit encoding", Left+40, y);
        y -= 2*INCRY;
        PDF_set_parameter(p, "charref", "true");
        Font_CS = PDF_load_font(p, "STSong-Light", 0, "UniGB-UCS2-H", "");
        for (i = 0; i < tsize_16; i++) {
            PDF_setfont(p, Font_H, 14);
            sprintf(text, "%s encoding, %s textformat %s: ", table_16[i].encname, table_16[i].textformat, table_16[i].bomkind);
            PDF_show_xy(p, text, Left, y);
            y -= INCRY;
            PDF_setfont(p, Font_CS, 14);
            sprintf(buf, "textformat %s",table_16[i].textformat);
            PDF_fit_textline(p, table_16[i].textstring, *table_16[i].textlength, Left, y, buf);
            y -= INCRY;
        }

        /* End of page. */
        PDF_end_page_ext(p, "");
        PDF_end_document(p, "");
    }
    PDF_CATCH(p) {
        printf("PDFlib exception occurred in pdflib_cs4 sample:\n");
        printf("[%d] %s: %s\n", PDF_get_errnum(p), PDF_get_apiname(p), PDF_get_errmsg(p));
        PDF_delete(p);
        return(2);
    }
    PDF_delete(p);
    return 0;
}

關鍵要點總結

1. 根據語言特性選擇 textformat：C/C++ 等 non-Unicode-capable 語言預設 auto，通常無需額外設定；Java/.NET 等建議顯式使用 utf16 或 utf8。
2. BOM 處理：utf16 會自動識別並剝離 BOM；utf16be/utf16le 則不處理 BOM，需確保資料端序正確。
3. 字符引用：啟用 charref 後可在 ASCII 字串中內嵌 Unicode 字符，便於在不支援寬字符的環境下輸出特殊符號。
4. 編碼與字體匹配：輸出中文時，需搭配 Unicode 編碼（如 UniGB-UCS2-H）與對應 CID 字體（如 STSong-Light）。

掌握這些文本輸入形式，能讓您在 PDFlib 中靈活、正確地處理多語言文本輸出，避免亂碼與字符缺失問題。