API 参考手册

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

请求体是单个 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: 自定义文件名，binary 和 file 都可用
• 默认行为是 binary
• 两种模式都返回 PDF 二进制
• binary 会返回 Content-Disposition: inline; filename="..."
• file 会返回 Content-Disposition: attachment; filename="..."
• 未提供 file_name 时回退到 gPdf-MMDDHHmmssSSS.pdf

元素类型

elements[] 当前支持：

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

图片支持：

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

条码 format 当前大小写不敏感，并将 - 与 _ 视为等价分隔符。

当前构建支持的条码格式：

• 2D / 矩阵类：qrcode(qr)、microqr(micro-qr)、pdf417、micropdf417(micro-pdf417)、datamatrix(data-matrix)、gs1datamatrix(gs1-datamatrix, gs1_datamatrix)、aztec、maxicode、gs1qrcode(gs1-qrcode, gs1_qr, gs1-qr)
• 1D / 线性类：code128(code-128)、code128a(code-128a)、code128b(code-128b)、code128c(code-128c)、gs1128(gs1-128)、code39(code-39)、code93(code-93)、codabar、ean8(ean-8)、ean13(ean-13)、upca(upc-a)、upce(upc-e)、itf(interleaved2of5)、itf14(itf-14)、gtin8(gtin-8)、gtin12(gtin-12)、gtin13(gtin-13)、gtin14(gtin-14)、isbn(isbn-13)、sscc(sscc-18)
• 其他业务类：msi(msi-plessey)、msi10(msi-10)、msi11(msi-11)、msi1010(msi-1010)、msi1110(msi-1110)、upus10(s10)、uspsimb(usps-imb, intelligent-mail)、upcacomposite(upca-composite)、upcecomposite(upce-composite)

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 时必须提供宽度：
  • 纯文本 / spans 简写使用 style.width
  • block text 使用 frame.width

统一矢量样式

矢量元素统一使用：

• stroke: StrokeStyle
• fill: FillStyle

这套样式同时适用于 line / rect / circle / ellipse / polygon。表格边框也统一复用同一套 StrokeStyle，包括 grid.top/right/bottom/left/horizontal/vertical 和 cell.borders。

StrokeStyle 支持可选的 compound 复合描边；当前公开支持的 kind 只有 double。

超链接模型

• 附着式链接：text / barcode / line / rect / circle / ellipse / polygon / image 可选挂载 link: LinkSpec
• 独立热点：type: "link" 用于定义无可见图形的点击区域
• LinkSpec.target 支持：
  • URL：{ "type": "url", "url": "https://..." }
  • 页内跳转：{ "type": "page", "page": 2, "x": 10, "y": 20 }
• URL scheme 当前限制为 http、https、mailto、tel
• 非法链接字段会直接校验报错，不会静默忽略

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
• 复杂正文单元格统一使用 content；分组表头 content 与 columns[].header 共享同一文本 contract（string | number | boolean | null | BlockTextContent）
• TableCellStyle 支持 content_offset_x / content_offset_y
• 旧轻量化字段 data/layout/theme/row_headers/corner/style_overrides 已不再属于公开接口

文本排版行为

• 公开 text 支持 3 种输入形式：

  • 纯文本简写
  • spans 富文本简写
  • block text

• 这 3 种写法在校验与渲染阶段会得到一致处理

• block text 的表达能力最完整，也是最推荐的写法

• text.rotation 支持任意整数角度

• image.rotation 支持任意角度

• barcode.rotation 与附带的 barcode_text 当前只支持 0/90/180/270

• 对 POST /api/v1/render，当前只公开保证 system.page 与 system.total_pages

• 如果你需要业务数据替换，请使用 POST /api/v1/template-render

• computed 当前未作为公开能力开放

• _if 属于模板元数据，POST /api/v1/render 不会执行 _if

• font_family 为空或不传：

  • 本层继续继承上层字体意图
  • 若整条链都没有显式字体，则进入自动字体模式

• font_family 有值但 font_mode 不传：

  • 默认 strict

• font_mode = "strict"：

  • 当前作用域必须完全由该字体覆盖

• font_mode = "prefer"：

  • 当前字体为首选，缺字时仍允许系统回退

• font_weight 支持 normal | medium | semibold | bold

• font_style 支持 normal | italic

• strict 下，请求的字重 / 斜体必须命中真实 face

• prefer 和自动模式会优先使用目标字重 / 斜体，找不到时才回退到最近可用 face

• font_mode 不能脱离同层 font_family 单独出现

• 对客请求当前只应使用 strict 与 prefer

• letter_spacing 是单个数字倍数参数

• 不传 letter_spacing 时，不生效

• 0 表示不加字距

• 大于 0 时按固定步长统一加字距

• 当前标准步长固定为 0.2em

• 例如：

  • 0.2 = 0.04em
  • 1 = 0.2em
  • 1.12 = 0.224em
  • 2 = 0.4em

• 不再支持自动字距

• background、decoration、link_style 都是 TextStyle 的对象字段

• background.padding 使用逻辑方向：

  • inline
  • block
  • 可选 *_start / *_end

• 文本背景没有单独的 preset 枚举；Square、Soft、Capsule 都只是参数组合

• 当前推荐默认：

  • badge 使用 Square
  • highlight 使用 Soft
  • Capsule 是可选风格，不作为默认

• span.style 可以覆盖排版字段，但不能覆盖 width、height、对齐等 box 级字段

默认值说明

服务默认值由系统统一应用；当请求未提供对应字段时，会自动补齐。

完整字段请继续查看：

• JSON 数据结构