PDF 生成模板编辑器
开源可视化 PDF 生成引擎,支持自定义模板,并提供面向开发者的 API,灵活构建文档生成流程。
如果您还没有获取许可证密钥,请查看如何获取许可证密钥。
ComPDFKit 转换 SDK 目前支持离线认证的方式验证许可证密钥。
了解关于:
复制许可证密钥
正确获取许可证密钥,是许可证应用的关键。
<type> 字段判断许可证类型,如果是 <type>online</type> 则为在线许可证, <type>offline</type> 或无该字段则为离线许可证。在线许可证:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<license version="1">
<platform>windows</platform>
<starttime>xxxxxxxx</starttime>
<endtime>xxxxxxxx</endtime>
<type>online</type>
<key>LICENSE_KEY</key>
</license>离线许可证:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<license version="1">
<platform>windows</platform>
<starttime>xxxxxxxx</starttime>
<endtime>xxxxxxxx</endtime>
<key>LICENSE_KEY</key>
</license><key>LICENSE_KEY</key>字段中的LICENSE_KEY应用许可证密钥
在您的项目中使用 ComPDFKit Conversion SDK 的类和方法之前,您需要先应用 License(许可证密钥)初始化该 SDK。
// 引入头文件。
#include "compdf_common_c.h"
#include "compdf_conversion_c.h"
// 验证 license。
const char* license = "LICENSE_KEY";
CSDKErrorCode code = CPDF_LicenseVerify(license, "device_id", "app_id");
if (code != e_CErrSuccess) {
return code;
}
// 初始化转档资源,参数为 SDK 包内 resource 目录的路径。
CPDF_Initialize(CPDF_TEXT("ComPDF_Conversion_SDK/resource"));查询授权类型
授权验证成功后,可以调用 CPDF_GetLicenseType 查询当前已验证的授权类型。该接口不会重新验证授权,也不消耗页数额度。
| 返回值 | 含义 |
|---|---|
e_CLicenseUnknown(0) | 尚未验证授权、验证失败,或 SDK 正在释放 |
e_CLicenseTrial(1) | 试用授权 |
e_CLicenseFormal(2) | 正式授权 |
CLicenseType type = CPDF_GetLicenseType();
if (type == e_CLicenseTrial) {
// 试用授权。
}C 接口约定
头文件
| 头文件 | 说明 |
|---|---|
compdf_common_c.h | 许可证验证、初始化、资源释放、页数、版本以及 DocumentAI 模型配置。 |
compdf_conversion_c.h | 文档转换接口。 |
compdf_basictypes_c.h | 错误码、转换选项、图片类型、OCR 语言等公共 C 类型。 |
路径字符串类型
大部分文件路径参数的类型为 COMPDFKIT_STRING:Windows 上为 const wchar_t*(例如 L"input.pdf"),Linux 和 macOS 上为 UTF-8 编码的 const char*。为便于跨平台,本指南的示例使用以下辅助宏(由本指南定义,不是 SDK 提供的接口,可按需复制到您的工程中):
#if defined(_WIN32)
#define CPDF_TEXT(text) L##text
#else
#define CPDF_TEXT(text) text
#endifCPDF_LicenseVerify 例外:其 license、device_id、app_id 参数始终为 const char*。
转换选项初始化
CConvertOption 是普通的 C 结构体,没有构造函数,使用前必须初始化。推荐直接使用头文件提供的默认值宏:
CConvertOption option = CPDF_CONVERT_OPTION_DEFAULT;本指南的示例使用以下辅助函数(由本指南定义,不是 SDK 提供的接口),它返回与 CPDF_CONVERT_OPTION_DEFAULT 相同的默认值:
static CConvertOption CPDF_DefaultConvertOption(void)
{
CConvertOption option = CPDF_CONVERT_OPTION_DEFAULT;
return option;
}注意: 如果使用
memset或{0}将CConvertOption清零,table_recognition_accuracy会是 0,即e_CHighAccuracy,而默认值为e_CBalanced。清零初始化时请显式设置您依赖的每个选项。
接口一览
compdf_common_c.h:
| 接口 | 说明 |
|---|---|
CSDKErrorCode CPDF_LicenseVerify(const char* license, const char* device_id, const char* app_id) | 验证许可证,返回 e_CErrSuccess 表示成功。见 2.4.2 应用许可证密钥。 |
CLicenseType CPDF_GetLicenseType(void) | 查询当前已验证的授权类型,不重新验证、不消耗额度。见 2.4.4 查询授权类型。 |
void CPDF_Initialize(COMPDFKIT_STRING resource_path) | 初始化 SDK,resource_path 为 SDK 包内 resource 目录的路径。须在调用转换接口之前调用。 |
void CPDF_SetLogger(bool enable_info, bool enable_warning) | 设置日志级别:enable_info 为 true 时输出 info、warning 和 error 日志;否则 enable_warning 为 true 时输出 warning 和 error 日志;两者均为 false 时只输出 error 日志。 |
CSDKErrorCode CPDF_SetDocumentAIModel(COMPDFKIT_STRING model_path, int gpu_id) | 加载 DocumentAI 模型包,并与已加载的能力合并。gpu_id 为使用的 GPU 编号,-1 表示不使用 GPU。model_path 为空时返回 e_CErrInvalidArg;转换任务进行中或释放尚未完成时返回 e_CErrConverting。见 3.7.4。 |
void CPDF_SetDocumentAIModelCount(int layout_model_count, int table_model_count) | 设置版面分析模型与表格识别模型的实例数。请在开始转换之前调用;转换任务进行中或释放尚未完成时调用会被忽略。 |
void CPDF_ReleaseDocumentAIModel(void) | 释放已加载的全部 DocumentAI 模型。之后再使用 AI 功能需要重新调用 CPDF_SetDocumentAIModel。 |
int CPDF_GetPageCount(COMPDFKIT_STRING file_path, COMPDFKIT_STRING password) | 返回 PDF 文件的页数。文件无法打开(例如密码错误)时返回 0;库资源正在释放或配置时返回 -1。 |
int CPDF_GetRemainingPageQuota(void) | 返回剩余页数配额:>= 0 为剩余页数,-1 表示未初始化,-2 表示不限制,-3 表示配额文件已损坏。 |
void CPDF_GetVersion(char* version) | 将 SDK 版本号字符串(例如 "4.3.0")写入调用方分配的缓冲区,缓冲区需足够容纳该字符串(例如 32 字节)。 |
void CPDF_Release(void) | 释放 SDK 占用的全部资源。见 3.18 释放库资源。 |
compdf_conversion_c.h:除 Word 转 PDF 外,所有转换接口的签名相同:
CSDKErrorCode CPDF_StartPDFToXxx(
COMPDFKIT_STRING file_path, // 输入文件路径
COMPDFKIT_STRING password, // 打开 PDF 的密码,无密码时传空字符串
COMPDFKIT_STRING output_path, // 输出路径
CConvertOption options, // 转换选项
CConvertCallback* callback); // 可选回调,不需要时传 NULL| 接口 | 输出格式 | 章节 |
|---|---|---|
CPDF_StartPDFToWord | Word (.docx) | 3.8 |
CPDF_StartPDFToExcel | Excel (.xlsx) / CSV | 3.9、3.12 |
CPDF_StartPDFToPpt | PowerPoint (.pptx) | 3.10 |
CPDF_StartPDFToHtml | HTML (.html) | 3.11 |
CPDF_StartPDFToImage | 图片 | 3.13 |
CPDF_StartPDFToRtf | RTF (.rtf) | 3.14 |
CPDF_StartPDFToTxt | 文本 (.txt) | 3.15 |
CPDF_StartPDFToSearchablePDF | 可搜索 PDF (.pdf) | 3.16 |
CPDF_StartPDFToOfd | OFD (.ofd) | 3.16.1 |
CPDF_StartPDFToJson | JSON (.json) | 4.1 |
CPDF_StartPDFToMarkdown | Markdown (.md) | 4.2 |
CPDF_StartWordToPDF | PDF(输入为 Word 文档,签名不同) | 3.17 |
CConvertCallback(progress、cancel、handle 以及自定义 AI 回调)见 3.1、3.2 与 3.7.2。
CConvertOption 字段
下表的默认值即 CPDF_CONVERT_OPTION_DEFAULT 中的初始值:
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
enable_ai_layout | bool | true | 是否启用 AI 版面分析。开启 OCR 时版面分析自动启用。 |
enable_ai_table_recognition | bool | true | 是否启用 AI 表格识别,仅在版面分析启用时生效。 |
contain_image | bool | true | 是否在输出中包含图片,仅在 enable_ocr 为 false 时生效。 |
contain_page_background_image | bool | true | 是否在输出中包含页面背景图,仅在 enable_ocr 为 true 时生效。 |
json_contain_table | bool | true | PDF 转 JSON 时是否提取表格。 |
contain_annotation | bool | true | 是否包含注释。 |
excel_all_content | bool | false | PDF 转 Excel 时是否写入表格以外的文本、图片等内容。 |
excel_csv_format | bool | false | PDF 转 Excel 时是否以 CSV 格式保存表格。 |
enable_ocr | bool | false | 是否启用 OCR。 |
transparent_text | bool | true | 输出文档中的文本层是否透明(用于可搜索 PDF、OFD)。 |
txt_table_format | bool | true | PDF 转 TXT 时是否按表格结构写入表格文本。 |
image_path_enhance | bool | false | PDF 转图片时是否增强路径的显示效果。 |
formula_to_image | bool | true | 是否将公式转换为图片。 |
auto_create_folder | bool | true | 输出多个文件时,是否自动创建文件夹存放。 |
output_document_per_page | bool | false | 是否每页输出一个文件。 |
language_count | int | 0 | languages 数组中的语言数量。 |
image_scaling | float | 4.0 | 输出图片的缩放比例,1.0 为原始页面大小。 |
page_layout_mode | CPageLayoutMode | e_PageLayoutModeFlow | 页面布局模式,见 3.5。 |
excel_worksheet_option | CExcelWorksheetOption | e_CForTable | Excel 工作表的创建方式,见 3.9。 |
html_option | CHtmlOption | e_CSinglePage | HTML 输出方式,见 3.11。 |
ocr_option | COCROption | e_CAll | OCR 识别范围,见 3.6。 |
image_color_mode | CImageColorMode | e_CColor | 输出图片的色彩模式。 |
image_type | CImageType | e_CJPG | 输出图片的格式。 |
font_name | char[256] | 空 | 输出文档使用的字体名称,例如 "Arial",见 3.7.3。 |
page_ranges | char[256] | 空 | 转换的页码范围,例如 "1-3,5,7-9";空表示全部页面。 |
languages | COCRLanguage* | NULL | OCR 语言数组,共 language_count 个,最多使用 32 个。开启 OCR 但未指定语言时使用英文。 |
enable_document_orientation_classification | bool | false | OCR 识别前是否识别并矫正文档方向。仅在 enable_ocr 为 true 时生效,需要加载 document_process.model。 |
enable_document_dewarp | bool | false | OCR 识别前是否进行文档矫正。仅在 enable_ocr 为 true 时生效,需要加载 document_process.model。 |
enable_auto_page_size | bool | false | 输入为图片文件时,按图片分辨率匹配最接近的标准纸张,见 3.13。 |
custom_page_width | float | 0 | 输入为图片文件时指定输出页宽,单位为点,0 表示不指定。 |
custom_page_height | float | 0 | 输入为图片文件时指定输出页高,单位为点。 |
table_recognition_accuracy | CTableRecognitionAccuracy | e_CBalanced | 表格识别模型档位,见 3.7.1。 |
word_pdf_bookmark_mode | CWordPdfBookmarkMode | e_CWordPdfBookmarkNone | 如何生成 PDF 书签,仅对 Word 转 PDF 生效,见 3.17。 |
枚举取值
| 枚举类型 | 取值 |
|---|---|
CPageLayoutMode | e_PageLayoutModeBox(框排)、e_PageLayoutModeFlow(流排) |
COCROption | e_CInvalidCharacter、e_CScanPage、e_CInvalidCharacterAndScanPage、e_CAll,含义见 3.6 |
CExcelWorksheetOption | e_CForTable、e_CForPage、e_CForDocument,含义见 3.9 |
CHtmlOption | e_CSinglePage、e_CSinglePageWithBookmark、e_CMultiPage、e_CMultiPageWithBookmark,含义见 3.11 |
CImageColorMode | e_CColor(彩色)、e_CGray(灰度)、e_CBinary(黑白) |
CImageType | e_CJPG、e_CJPEG、e_CJPEG2000、e_CPNG、e_CBMP、e_CTIFF、e_CTGA、e_CGIF、e_CWEBP |
CTableRecognitionAccuracy | e_CHighAccuracy(0,高精度)、e_CBalanced(1,均衡) |
CWordPdfBookmarkMode | e_CWordPdfBookmarkNone、e_CWordPdfBookmarkHeadings、e_CWordPdfBookmarkWordBookmarks,含义见 3.17 |
COCRLanguage | e_CUNKNOWN(未知)、e_CCHINESE(简体中文)、e_CCHINESE_TRA(繁体中文)、e_CENGLISH(英文)、e_CKOREAN(韩文)、e_CJAPANESE(日文)、e_CLATIN(拉丁字母语言)、e_CDEVANAGARI(天城文)、e_CCYRILLIC(西里尔字母语言)、e_CARABIC(阿拉伯文)、e_CTAMIL(泰米尔文)、e_CTELUGU(泰卢固文)、e_CKANNADA(卡纳达文)、e_CTHAI(泰文)、e_CGREEK(希腊文)、e_CEslav(斯拉夫语)、e_CAUTO(自动选择语言) |
错误码
大部分接口返回 CSDKErrorCode,e_CErrSuccess 表示成功。调用转换接口后请检查返回值。
| 错误码 | 值 | 含义 |
|---|---|---|
e_CErrSuccess | 0 | 成功。 |
e_CErrCancel | 1 | 转换被取消。 |
e_CErrFile | 2 | 文件不存在或无法打开。 |
e_CErrPDFPassword | 3 | 密码错误。 |
e_CErrPDFPage | 4 | PDF 页面加载失败。 |
e_CErrPDFFormat | 5 | 格式无效,文件可能已损坏。 |
e_CErrPDFSecurity | 6 | PDF 使用了不支持的加密方式。 |
e_CErrOutOfMemory | 7 | 内存不足;Word 转 PDF 时也表示诊断缓冲区放不下完整诊断信息。 |
e_CErrIO | 8 | 系统 I/O 错误。 |
e_CErrCompress | 9 | 文件夹压缩失败。 |
e_CErrLicenseInvalid | 20 | 许可证无效。 |
e_CErrLicenseExpire | 21 | 许可证已过期。 |
e_CErrLicenseUnsupportedPlatform | 22 | 许可证不支持当前平台。 |
e_CErrLicenseUnsupportedID | 23 | 许可证不支持该应用 ID。 |
e_CErrLicenseUnsupportedDevice | 24 | 许可证不支持该设备 ID。 |
e_CErrLicensePermissionDeny | 25 | 许可证不包含该功能权限。 |
e_CErrLicenseUninitialized | 26 | 许可证未初始化。 |
e_CErrLicenseIllegalAccess | 27 | 非法访问接口。 |
e_CErrLicenseFileReadFailed | 28 | 读取许可证文件失败。 |
e_CErrLicenseOCRPermissionDeny | 29 | 许可证不包含 OCR 权限。 |
e_CErrLicenseConcurrencyExceeded | 30 | 当前转换并发数超过许可证限制。 |
e_CErrLicensePageLimitExceeded | 31 | 转换页数超过许可证限制。 |
e_CErrLicenseQuotaCorrupted | 32 | 配额持久化文件被篡改。 |
e_CErrNoTable | 40 | 源文件中没有表格。 |
e_CErrOCRFailure | 41 | OCR 识别调用失败。 |
e_CErrConverting | 60 | 正在执行转换任务(例如转换进行中加载模型)。 |
e_CErrInvalidArg | 80 | 参数无效。 |
e_CErrInvalidHandle | 81 | 句柄无效,可能未初始化或已释放。 |
e_CErrModelInvalidFormat | 82 | 模型文件格式无效或已损坏。 |
e_CErrModelFunctionUnsupported | 83 | 模型不支持所请求的功能。 |
e_CErrModelFormatUnsupported | 84 | 不支持该模型格式。 |
e_CErrModelSDKMismatch | 85 | 模型与当前 SDK 版本不配套。 |
e_CErrImageDataEmpty | 86 | 图像数据为空。 |
e_CErrImageWHError | 87 | 图像宽高无效。 |
e_CErrImageUnsupportedFormat | 88 | 不支持该图像格式。 |
e_CErrImageInvalid | 89 | 图像无效或已损坏。 |
e_CErrExpire | 90 | 资源(例如许可证)已过期。 |
e_CErrMissingArg | 91 | 缺少必需的参数。 |
e_CErrLicenseUnsupportedAPI | 92 | 当前许可证不支持调用该接口。 |
e_CErrLicenseMismatch | 93 | 许可证与设备、模块或版本不匹配。 |
e_CErrInvalidTable | 94 | 表格数据无效或为空。 |
e_CErrUnsupportedFeature | 95 | 输入包含无法完全还原的特性,或目标格式无法承载输入内容。可能仍有可用输出(Word 转 PDF 通常仍会生成 PDF),见 3.13 与 3.17。 |
e_CErrUnknown | 100 | 未知错误。 |