API 参考手册

当前唯一 canonical 路由为 POST /api/v1/label。

请求体是单个 DocumentRequest JSON 对象，不再接收旧的数组式 LabelRequest[]。

根对象：DocumentRequest

字段	类型	必填	说明
settings	Settings	否	全局默认样式、元数据、PDF/A profile
pages	Page[]	是	页面数组
header	Section	否	全局页眉
footer	Section	否	全局页脚

页面尺寸

每一页必须显式指定尺寸，二选一：

• width + height
• size

规则：

• size 与 width/height 互斥
• width 与 height 必须一起提供
• size 不区分大小写

支持的预设：

• a4
• a6
• letter
• legal
• label_100_100
• label_100_150
• label_4_6_in

header / footer

两者共用同一个 Section 结构：

• height: number
• elements: Element[]

语义：

• header 会重复应用到每一页
• footer 会重复应用到每一页
• header 按页面绝对坐标渲染
• footer 会自动下移到页面底部区域
• footer.height 会压缩正文可用高度
• header 不会自动把正文整体下移
• 可选的 settings.page_margin / pages[].margin 用于定义正文 content box
• 配置页边距后，正文 x/y 改为相对 content box
• 正文元素超出 content box 会直接校验报错

Settings

字段	类型
defaults	Defaults
metadata	Metadata
output	OutputSettings
profile	string
page_margin	PageMargin

OutputSettings

• mode: binary 或 file
• file_name: 自定义文件名，仅 mode = "file" 时生效
• 默认行为是 binary
• 未提供 file_name 时回退到 gPdf-MMDDHHmmssSSS.pdf

元素类型

elements[] 当前支持：

• text
• barcode
• line
• rect
• circle
• ellipse
• polygon
• link
• image
• table
• stack

图片支持：

• 位图：jpg / jpeg / png / webp
• 矢量：svg

stack

• 仅用于 pages[].elements
• 解决 table 后面继续跟随一个或多个内容块的问题
• children[0] 必须是 table
• 后续 child 只能是 block
• gap 表示 table 最终底部到下一个 block 起点的垂直距离

block

• stack 内的跟随内容块
• 不提供自己的 x/y/width/height
• 内部元素的 x 继续沿用现有 body 语义
• 内部元素的 y 是相对 block 起点的偏移
• 不允许再嵌套 table / stack / block

x_anchor

• 当前支持 text、barcode、rect、image、link
• 与 x 互斥
• 全局可使用 page_* 与 content_*
• table_left / table_right 仅允许在 stack -> block
• text 使用 x_anchor 时必须提供 style.width

Table

当前公开 table schema 只支持这组正式字段：

• columns
• rows
• cell
• header
• row_header
• body
• grid
• pagination

关键规则：

• 行表头通过 columns[].role = "row_header" 表达
• grid 与单元格边框统一复用 StrokeStyle
• columns[].width 统一使用 fixed / percent / auto
• percent 和 auto 依赖 table.width
• 分组表头通过 header.rows 表达，叶子表头仍使用 columns[].header
• TableCellStyle 支持 content_offset_x / content_offset_y
• 旧轻量化字段 data/layout/theme/row_headers/corner/style_overrides 已不再属于公开接口

运行时配置

运行时默认值通过 GET /v1/xpdf/runtime-config 分发，worker 与 server 使用同一份来源，不再依赖旧的公开轻量化 payload。

完整字段请继续查看：

• JSON 数据结构