JSON 与 C ABI 文档操作

export.structured 把选定页面导出为语义 HTML、XHTML、XML 或 JSON；tables.export 把类型化表格导出为 CSV、JSON 或 XLSX，保留跨页连续性、合并单元格和原生的值推断

两种操作都要求二进制输出目的地，保持文档与既有签名字段不变，并暴露有界的原生导出选项

结构化与类型化表格导出

{"schemaVersion":1,"type":"export.structured","pages":[0,1],"format":"html",
 "options":{"imageMode":"metadata","includeFormControls":false}}

{"schemaVersion":1,"type":"tables.export","pages":[0,1],"format":"json",
 "options":{"mergeAcrossPages":true,"dateOrder":"dmy",
            "decimalSeparator":",","thousandsSeparator":"."}}

结构化导出接受 html、xhtml、xml 和 json（默认）；表格导出接受 csv（默认）、json 和 xlsx

结构化布尔选项有 includeCoordinates、includeStyles、includeImages、includeTables、includeAccessibilitySemantics、preferTaggedStructure、fallbackToGeometricSemantics、includeNavigation、includeAnnotations 和 includeFormControls，全部默认为 true

imageMode 接受 omit、metadata 和 embedded-png（默认）；语义模型与敏感字段行为参见 结构化已加载页面导出

结构化资源选项有 maxPageCount、maxGlyphsPerPage、maxImagesPerPage、maxStructureNodes、maxOutlineItems、maxInteractionsPerPage、maxFormOptionsPerField、maxOutputBytes、maxImageBytes 和 maxTotalImageBytes

表格布尔选项有 detectMergedCells、detectRepeatedHeaders、mergeAcrossPages 和 inferValueTypes，全部默认为 true

dateOrder 接受 ymd（默认）、mdy 和 dmy；分隔符必须是单个可打印字符，空的 thousandsSeparator 表示禁用千位分隔

minimumTableConfidence 接受 0 到 1，默认 0.55；正的 columnTolerance 默认为 12 个页面单位

表格资源选项有 maxPageCount、maxGlyphsPerPage、maxTableCount、maxRowCount、maxCellCount、maxTextCharacters 和 maxOutputBytes；单元格模型参见 类型化表格提取

未知的选项名、无效类型、不受支持的格式和非正数限制都会被拒绝；请求的原生上限还会被保守的内存与对象预算进一步收紧

导出暂存的上限取 budget.outputBytes 与 budget.memoryBytes 四分之一两者中的较小值；effectiveOutputLimit 报告该上限，而更紧的 options.maxOutputBytes 也可能生效

原生资源失败会报告 budget-exceeded、指标 nativeExportResources 和原生诊断信息；observed=1 且 limit=0 表示资源被拒绝，而不是实测的字节用量

两种操作都报告 documentUpdated: false，保留源的自动启动与解码设置，先暂存输出再发布，文件任务失败时保留既有文件目的地

截止时间与 ABI 回调取消检查在操作和发布检查点是协作式的；原生取消令牌同样作用于受支持的提取阶段内部，但原生工作不会被强制中断

THPDFJobProcessor.ExecuteLoadedOperation 与 hpdf_document_execute_json_v1 共享同一套带 schema 版本的文档操作引擎

通过 THPDFJobProcessor.Capabilities 或 hpdf_capabilities_json_to_io 可以发现当前的操作名、格式、签名配置文件、回调行为和默认预算

操作

操作 JSON 使用 UTF-8 和 schemaVersion: 1；页面索引从零开始，选定页面数组不能包含重复项

当原生替换 API 无法编码某个匹配时，文本替换会返回部分完成状态；请检查其每页计数

外部 OCR 作业在内置 ASCII 默认引擎之外接受显式配置的 Tesseract CLI/DLL 与 RapidOCR CLI/DLL 引擎，带类型化设置、引擎超时、像素上限和原子发布

修改类操作会拒绝带既有签名字段的文档，包括未签名的占位符；要在这类文档中保留签名，请使用原生增量 API

增量 PFX 签名接受未修改的留存源，包括带显式操作口令的受支持加密 PDF，校验每个新旧 CMS，保留原始字节和加密，支持既有的空签名字段，检查加密权限，并拒绝源/输出文件互为别名

签名会产出已签名的产物并恢复原始句柄，报告 documentUpdated: false；既有表单字段保持可用，临时签名字段被移除，签名之后句柄仍可查询或用于另一次操作

PDF/A-4 栅格归档转换

{
  "schemaVersion": 1,
  "type": "archive.pdfa4.raster",
  "acceptInformationLoss": true,
  "iccProfileFile": "profiles/sRGB.icm",
  "dpi": 150,
  "input": "source.pdf",
  "output": "archive.pdf"
}

把这个对象放进文件任务的 operations 数组，或者在已加载句柄和二进制输出回调之下直接通过 hpdf_document_execute_json_v1 提供；C ABI 会忽略文件任务的输入/输出路径并使用自己的适配器

acceptInformationLoss 必须是 JSON 布尔值 true；iccProfileFile 必须给出一个非空、不含 NUL 的路径，指向执行主机上受支持的 sRGB matrix/TRC ICC 配置文件；相对配置文件路径按进程工作目录解析

dpi 默认 150，接受 36 到 1,200 的整数；转换覆盖每一个源页面，并拒绝任何 pages 成员

archive 结果对象报告 nativeValidationSucceeded、sourcePages、pagesRendered、rasterPixels、outputBytes、removedAnnotations、removedFormFields 和 removedEmbeddedFiles

archive.lossy 为 true，archive.lossProfile 中的每个标志都是 false：searchableText、vectorContent、interactiveContent、originalSignatures、annotationAppearances 和 structureIdentity

页面内容变成 RGB 像素；注释和控件外观被省略，原始签名不会带入输出；已加载源在 documentUpdated: false 下保持可用，即使发布失败也不例外；其先前的启动、解码、流阈值、取消和渲染设置都会恢复

要求二进制输出，且原生 PDF/A-4 验证必须在交付之前通过；渲染、颜色、编解码器、源别名和一致性边界参见 已加载 PDF 的 PDF/A-4 栅格转换

归档资源预算

可选的 options 对象接受正的精确整数，用于收紧下列生效上限；未知键和超过上限的值会拒绝请求，而不是扩大操作预算

ICC 文件在分配之前上限取 4 MiB 与 memoryBytes / 16 中的较小值；这些保守的额度同时顾及了并发的暂存、输出缓冲、图像数据和解码器工作，并不构成严格的进程 RSS 限制

归档工作负载确实很大时，应调高顶层的任务预算；嵌套选项只能收紧生效上限，原生最大值依然适用

归档检查点在转换期间轮询回调取消、借用的源取消令牌、已用时间和对象计数；预算与取消失败在整个原生转换器中保留其结构化状态码

文件任务

{
  "operations": [
    {"type": "capabilities"},
    {"schemaVersion": 1, "type": "text.extract", "input": "input.pdf",
     "pages": [0, 1], "output": "text.txt"}
  ]
}

THPDFJobProcessor.Execute 接受一个 operations 数组，最多 1,024 个操作和 4 MiB JSON；既有的合并、拆分、优化、加密和验证任务继续可用

每个文档操作都要提供输入路径和可选密码；render、text.replace、forms.fill、forms.flatten、ocr.layer、redact、sign 和 archive.pdfa4.raster 还要求输出路径

产物先写入目的地旁边的临时文件，刷新并验证后再原子化发布；失败时保留既有目的地，输入/输出可以共用同一路径

C 回调契约

把 hpdf_operation_v1 零初始化，struct_size 设为其原生大小，abi_version 设为 HPDF_ABI_VERSION_1，flags 设为零；并将其大小与 hpdf_abi_operation_v1_size 比较

操作记录携带 JSON 字节和精确长度、可选的随机访问输入、可选的顺序二进制输出，以及必需的顺序 JSON 结果输出

由于惰性解析会保留适配器，输入回调、用户数据和支撑 PDF 的字节必须保持有效，直到句柄被替换或销毁

输出/结果回调只在调用期间存在；对每个句柄串行化调用，避免回调重入

回调使用 cdecl，部分传输会重试，成功的写入必须有实质进展；异常被转换为固定状态码

只有产物和 JSON 结果都成功交付之后，修改才会提交；回调失败或取消会回滚变更，调用方应丢弃已经交付的字节

替换输入在修改事务之前加载，并保持为独立的状态变更

预算

可选的预算对象接受不大于 9,007,199,254,740,991 的正精确整数

通用输出/结果预算各自封顶为内存预算的一半；归档转换适用上文更严格的上限；这些约束限制的是已配置的操作资源，而不是进程总内存

取消与已用时间检查在操作、页面、输入读取和输出写入检查点是协作式的；长时间运行的原生例程可以继续执行到它的下一个检查点

报告携带 schemaVersion、status 和 statusCode；预算错误使用 status 8，取消为 4，I/O 失败为 5，解析失败为 6，无效参数为 1，执行失败为 7