ComPDF Generation 用户操作指南

概览

本文档用于帮助您快速掌握 ComPDF Generation 模板编辑器的核心操作流程，完成从新建 HTML 模板、导入 JSON 数据源、插入占位符，到最终生成并导出 PDF 文件的完整工作。无论您是首次使用，还是需要将模板交付给团队复用，都可以按照本文步骤完成配置与生成。

完成部署后，您将进入 ComPDF Generation 模板编辑器主界面。为便于快速上手，建议您先阅读“快速上手”章节，优先完成第一份 PDF 的生成；如需进一步掌握表格填充、数据格式处理和导出排查，再继续阅读后续章节。

术语说明：

• HTML 模板：用于定义 PDF 内容、样式和排版结构的模板文件。
• 数据源：用于填充模板内容的 JSON 数据。
• 占位符：模板中用于接收 JSON 字段值的变量标记。
• 导出 PDF：系统将模板与数据源合并后，输出最终 PDF 文件。

快速上手

如果您希望先完成一次最小闭环操作，建议按照以下顺序进行：

1. 新建一个 HTML 模板
2. 导入一份 JSON 数据源
3. 在编辑器中插入占位符
4. 保存模板
5. 导出 PDF

以下是一份可用于测试的最小 JSON 示例：

{
  "customer_name": "ACME Corp",
  "invoice_no": "INV-20260802",
  "amount": 1280.5,
  "date": "2026-08-02"
}

建议您先在富文本模板编辑器中输入如下示例内容：

客户名称：{{customer_name}}
发票编号：{{invoice_no}}
金额：{{amount}}
日期：{{date}}

完成后导出 PDF，即可快速验证模板、数据源与占位符是否配置正确。

新建与管理 HTML 模板

本章节将介绍如何创建新的 HTML 模板，并在模板管理中心完成后续的查看与管理操作。

操作步骤

1. 点击首页中的新建模板按钮。
2. 在弹窗中填写模板名称和模板描述。
3. 提交后，模板会显示在模板管理中心。
4. 在模板列表中，您可继续执行导入、下载、编辑、删除、设计等操作。

适用场景

• 按业务类型区分模板，如发票、合同、报价单、报告
• 为不同客户或不同地区维护独立模板版本
• 为后续批量生成建立标准模板库

导入模板

在模板列表中点击导入模板，选择文件后即可创建对应的模板。支持以下文件格式：

• .zip、.dito：导入模板包并创建对应模板。

导入完成后，您可在模板列表中打开模板并继续编辑、配置数据源或导出 PDF。

设计 HTML 模板

完成模板创建后，您可以进入编辑器，对模板内容、排版结构和基础样式进行设计与调整。

操作说明

您可以通过编辑区像处理文档一样设计模板内容，自由添加文字、图片、段落、表格和样式布局。

两种常见方式

1. 从零开始创建模板 适用于首次设计新文档版式的场景，您可以自由输入内容并调整布局。

2. 基于已有模板继续修改 适用于复用历史模板的场景，您可将已有 HTML 模板内容复制后粘贴到编辑器中，再继续优化。

建议

• 先确认文档结构，再完善样式细节
• 对于正式业务文档，建议先完成内容占位，再统一调整格式
• 如模板中包含图片，请提前确认图片路径或链接可正常访问

导入数据源

在开始插入动态内容之前，您需要先导入 JSON 数据源，让系统识别可用于映射的字段。

操作步骤

1. 进入设计模板页面。
2. 点击导入数据源相关入口。

3. 选择以下任一方式导入数据：

• 上传 JSON 文件

• 直接输入 JSON 代码

4. 导入成功后，系统会在右侧数据源面板中展示已识别字段。

重要提醒

• JSON 必须为正确格式，否则无法识别或导入数据源时会报错
• 模板中使用的占位符字段，必须存在于 JSON 数据中
• 数据源与 HTML 模板中的字段名需要完全一致，区分大小写时请特别注意。您可以直接在数据源列表中的数据字段一键插入到 HTML 模板的光标位置，避免手动输入出错。
• 如果后续需要生成图片、日期、布尔值等内容，建议在数据源中提前规范字段类型

设置 JSON 字段格式

如果您对字段的显示结果有特定要求，可以在本章节中进一步设置数据格式，以满足不同业务文档的展示需求。

适用场景

• 数值计算、取整、比较判断
• 日期格式统一
• 文本拼接或大小写转换
• 图片宽高控制
• 布尔值转换为业务语言

操作说明

若您希望调整占位符最终呈现的数据格式，请点击下图中标出的按钮，即可对字段进行相应设置。常见配置包括数值运算、条件判断、日期格式转换等。

支持处理类型

类型	支持处理
文本	拼接字符串、转大写、转小写
数值	加法、减法、乘法、除法、幂运算、取模、四舍五入、求两数乘积、整除判断、奇偶判断、大小比较、相等比较、货币符号和符号位置设置
日期	MM/DD/YYYY、DD/MM/YYYY、YYYY-MM-DD、YYYY-MM-DD HH:mm:ss
图片	宽（px）、高（px）
布尔	真值显示文本、假值显示文本

建议

• 在正式导出前，建议先用测试数据验证格式结果
• 日期和金额是最常见的格式问题，建议优先检查
• 若涉及条件判断，建议准备至少两组测试数据分别验证

货币符号

将字段类型设置为数值后，可选择货币格式、货币符号及符号位于金额前或后。支持 US$、$、€、¥、£、CN¥、CHF、A$、CA$、HK$、S$、₹、₩、NT$、R$、R、Rp、₺、฿、RM、د.إ、ر.س、₽ 和 ₫ 等货币符号。

插入占位符

完成数据源导入后，您可以将字段以占位符形式插入到模板中的指定位置，以便系统在生成 PDF 时自动替换为实际数据。

如果某些字段在生成的 PDF 中有特定显示要求，例如金额需显示币种、字符需全部大写、数值需基于 JSON 数据进行运算等，请先参照 设置 JSON 字段格式 章节完成配置，再将字段插入 HTML 模板。

操作步骤

方式一：在左侧编辑器中将光标定位到需要插入数据的位置。在右侧数据源面板中选择目标字段，并点击插入按钮将字段写入 HTML 模板。

方式二：您可以在数据源列表中点击复制按钮，再粘贴到左侧富文本编辑器中。

点击插入后，系统会将该字段以占位符形式写入当前光标位置。完成模板设计后，导出 PDF 时系统会自动进行数据替换。

表格与循环块

如果您需要在模板中填充列表或明细数据，可以参考本章节的演示，将表格数据按行插入到 HTML 模板中。

演示说明

可以先在数据源中准备好表格对应的列表数据，再在 HTML 模板的表格中设置一行作为循环行，并在该行内插入字段占位符。

生成文档时，系统会按照数据源中的列表条数，自动循环复制这一行，并完成每一行的数据填充。

动态表格操作步骤

步骤一：在数据源中准备列表类型的数据，例如订单明细、商品信息或费用清单。

步骤二：在 HTML 模板中插入表格，并保留一行作为明细数据展示行。该行将作为循环块进行自动填充 JSON 数据。

步骤三：在数据行的左侧首个单元格中插入对应字段的占位符，例如名称、数量、单价、金额等。

步骤四：检查占位符与 JSON 字段名称是否一一对应。生成文档后，系统会根据列表数据条数自动新增行，并填充对应内容。

适用示例

• 将客户名称插入到页眉或合同抬头
• 将订单金额、日期、编号等字段插入正文
• 将图片字段插入证件、商品展示或品牌标识位置

重要提醒

• 占位符名称必须与 JSON 字段一一对应
• 建议先完成数据源导入，再统一插入占位符
• 如果模板中字段较多，建议按区域分批插入，便于后续排查

保存模板

完成模板编辑后，建议及时保存当前内容，便于后续继续修改、版本留存或跨场景复用。

编辑器顶部提供两种保存选项，可根据使用场景选择：

• 保存修改：直接覆盖当前模板，适用于对已有模板进行更新。
• 另存为新模板：基于当前模板创建新版本，适用于衍生多个业务模板或保留历史版本。

导出模板与 PDF

下载 HTML 模板

点击顶部下载 HTML 模板按钮，系统会导出模板压缩包，便于进行本地备份、团队共享、归档管理或后续迁移。

下载包通常包含：

• HTML 模板文件
• JSON 源数据文件（如有）
• 模板信息文件

生成并导出 PDF

打开目标模板编辑页后，请先确认以下内容：

1. 左侧 HTML 内容已完成
2. 右侧 JSON 数据有效
3. 所有占位符均已正确映射
4. 当前模板已保存

确认无误后，点击顶部导出 PDF即可生成文件。

常见问题与排查建议

如导出失败或结果异常，建议按以下顺序排查：

1. 模板未保存

如果刚完成编辑但尚未保存，系统可能无法基于最新内容导出 PDF。建议先点击保存修改，再重新导出。

2. JSON 格式有误

如果 JSON 数据结构错误、缺少括号或字段格式异常，系统将无法正常识别数据源。建议先校验 JSON 格式，再重新导入。

3. 占位符与字段名不一致

如果模板中的变量名与 JSON 字段不完全一致，系统将无法替换对应内容。建议重点检查字段拼写、大小写和层级结构。

4. 页面样式超出版心

如果模板中存在过宽表格、大尺寸图片或复杂布局，导出后可能出现换页异常、内容截断或显示错位。建议优先优化版式并使用测试数据验证。

5. 表格或复杂样式异常

对于多行表格、嵌套结构或复杂样式文档，建议先完成最小版本导出，再逐步增加内容，以便快速定位问题。