动态表单之后：如何构建一个PDF 打印引擎？

一、 前情回顾：数据收上来了，然后呢？

书接上回，在上一篇文章《从零构建动态表单引擎：告别重复劳动》中，我们聊到了如何通过元数据驱动，解决活动报名中千变万化的信息收集难题。我们把"硬编码"变成了"配置化"，让运营人员像搭积木一样定义表单。

但随着项目推进，立刻迎来下一个挑战："收集上来的数据，要打印成标准格式的申报书，而且每个活动的打印格式都不一样。怎么办？"

好家伙，数据收集是动态的，打印报表自然也得是动态的。

起初，为了赶进度，我用的传统方法：先用固定表单的模式编写了一个PDF方法类。项目初期我可以这么干，可如果后续有100个活动，我就要写100个类？这不符合构建动态引擎的初衷。

我需要的是一个通用的渲染引擎：它只负责"画图"，至于"画什么"，由配置文件说了算。

二、 HTML 转 PDF 的"弯路"

在决定自研渲染引擎之前，我第一时间想到的方式是先动态编辑一个HTML模板，然后再转换成PDF。

逻辑很简单：前端先写个 HTML 模板，标签定位的方式替换真实的数据元素，然后用 wkhtmltopdf 或 Puppeteer 等插件转成PDF。这不就是浏览器渲染吗？多简单！

然而，当进入正式场景时，真是一坑又一坑啊：

1. 分页的痛：这是最大的痛点。HTML 本质是流式布局，它不懂"A4纸"的概念。当一个长表格跨页时，HTML 转换器经常会把文字切成两半，或者边框在页脚处断裂，极其难看，而且处理起来页很痛苦，很可能这个处理好了，下一个又不行。
2. 表头重复：正式报表要求表格跨页时，新页面的顶部必须重复表头。虽然 CSS 有一些特性约束，但在不同的转换引擎下表现极不稳定。
3. 样式问题：做打印表之前，一般用户会提供一个样例，按这个思路处理的话，很难百分百还原成HTML模板，而打印表的格式一般都比较正式，不会像网页一样花里胡哨。
4. **字段映射：**这个就和业务相关了，大体上是标签替换的时候要考虑数组对象和普通对象的区分，Mapping的代码非常繁琐。
5. 性能黑洞：html转pdf，性能是有较大损失的。

总之 ：如果你的需求是打印超市小票或简单的网页快照，HTML 方案没问题。但如果要打印格式严谨、分页完美、带有公章的申报书或者报表，我觉得这条路可能并不合适。

这里我附个图，这条路我还真的走了挺久，除了公章，图片这些特殊元素，基本的动态表单元素渲染都搞出来了，但最后打印的时候非常别扭。而且实际操作下来配置工作也并不轻松，还容易出错，尽管页面效果花了些功夫，有点不舍吧，但最终还是放弃了这条路；

三、 回归正途：基于 QuestPDF 的配置化引擎

QuestPDF 是一个基于 .NET 的开源 PDF 生成库。它的核心优势是Layout Engine（布局引擎），它完全遵循打印排版逻辑，支持完美的分页、断行和图层控制。

我们的目标是：构建一个"低代码"渲染器，让 JSON 配置文件指导 QuestPDF 工作。

---

注意：QuestPDF不是商业免费的，但官方提供了社区版，需要在使用时进行显示声明，这点大家可以查阅QuestPDF的官方文档。

3.1 核心架构：配置与引擎分离

我们将系统划分为两层：

• 配置层 (JSON)：这是"图纸"。它描述了文档有哪些章节、表格有几列、每个单元格绑定哪个数据字段。每次新活动，我们只需配置这个 JSON。
• 引擎层 (DynamicPdfEngine)：这是"工匠"。它是一套通用的后端代码，负责读取 JSON，解析动态数据，然后调用 QuestPDF 的 API 进行绘制。这是一次性编写，永久复用的。

3.2 布局设计：一切皆组件 (Section)

为了应对多变的格式，我将 PDF 文档拆解为不同的 Section 类型：

1. GridForm (不规则网格)：用于"基本信息"这种字段错落有致、不仅合并单元格的区域。
2. **DataTable(动态列表)：**用于"进度计划"、"人员名单"这种循环数据，支持自动分页和表头重复。
3. TextBlock (说明文本)：用于"填报说明"，支持多段落和自动缩进。
4. **StandaloneImage (独立图片)：**用于单独显示的证书扫描件或封面图等。

一个典型的配置片段如下：

{
  "type": "DataTable",
  "title": "四、执行单位主要参与人员",
  "dataGroupKey": 740719288971667, // 对应动态表单的 RoleId
  "columnsDefinition": [1, 2, 1, 2, 2], // 定义5列及其宽度比例
  "header": ["序号", "姓名", "年龄", "职务", "电话"],
  "rowTemplate": [
    { "type": "Index" }, // 自动序号
    { "bindKey": "Name" },
    { 
      "bindKey": "Birthday", 
      "transform": { "type": "CalculateAge" } // 👈 亮点：配置化计算
    },
    // ...
  ]
}

渲染引擎里的根据Section的类型执行不同的渲染方法

private void RenderSection(IContainer container, SectionConfig config)
{
    if (config.Type.Equals("StandaloneImage", StringComparison.InvariantCultureIgnoreCase))
    {
        RenderStandaloneImage(container, config);
    }
    else if (config.Type.Equals("TextBlock", StringComparison.InvariantCultureIgnoreCase))
    {
        RenderTextBlock(container, config);
    }
    
   // ..其他类型
   
}

四、 难点介绍

在开发过程中，遇到了几个棘手的问题，这里分享一下解决方案。

难点一：数据分组与映射

上篇博客提到，我们的动态表单数据结构是嵌套的 ( detailInfo+ memberInfos)。而在打印时，我们需要将 memberInfos 按照 DynamicRoleId 进行分组。

解决： 我编写了一个 RenderData 适配器，将复杂的原始 JSON 扁平化。在配置 DataTable 时，只需指定 dataGroupKey，引擎就会自动去匹配对应的子列表数据。

public RenderData(JObject root)
{
    // 解析 detailInfo -> detailDynamicFormData
    if (root["detailInfo"]?["detailDynamicFormData"] is JObject detailObj)
    {
#pragma warning disable CS8601 // 引用类型赋值可能为 null。
        DetailData = detailObj.ToObject<Dictionary<string, string>>();
#pragma warning restore CS8601 // 引用类型赋值可能为 null。
    }

    // 解析 memberInfos -> dynamicRoleId 分组
    var members = root["memberInfos"] as JArray;
    if (members != null)
    {
        foreach (var item in members)
        {
            var roleIdToken = item["dynamicRoleId"];
            var formData = item["memberDynamicFormData"]?.ToObject<Dictionary<string, string>>();

            if (roleIdToken == null || formData == null) continue;

            long roleId = roleIdToken.Value<long>();

            if (!GroupedListData.ContainsKey(roleId))
            {
                GroupedListData[roleId] = new List<Dictionary<string, string>>();
            }
            GroupedListData[roleId].Add(formData);
        }
    }
}

难点二：计算字段（配置里的"魔法"）

数据库里存的是"出生日期" (1990-01-01)，但打印表要求显示"年龄" (35)。如果我们在 C# 里硬写逻辑，就失去了动态化的意义。

解决： 我们在 JSON 配置中引入了 Transform 属性。引擎在渲染单元格时，会检查这个属性：

// 引擎内部逻辑
if (config.Transform?.Type == "CalculateAge") {
    return CalculateAge(originalValue);
}

这样，数据的展示形式完全由配置决定。

难点三：多源图片渲染（本地， 网络 ， Base64等）

打印表里既有上传的用户照片（Base64），又有固定的 LOGO（服务器本地文件），甚至可能有外部 URL。

解决： 我们定义了 ImageSourceType 枚举。引擎层注入了 IWebHostEnvironment，从而具备了读取 wwwroot 下本地资源的能力。

// 统一的图片获取逻辑
if (sourceType == ImageSourceType.LocalPath) {
    // 读取服务器本地 Logo
    path = Path.Combine(_env.WebRootPath, config.FixedValue);
} else if (sourceType == ImageSourceType.Base64) {
    // 从动态表单数据中取值
    base64Str = GetValueFromFormData(config.BindKey);
}

这解决了"固定 Logo"和"动态照片"混排的问题。

难点四：不可避免的复杂配置

不同的Section里，会有各种意想不到的配置要求，比如GridForm(不规则网格) 里某个元素有特殊的位置需求，同理其他类型里也可能有，再比如图片要限定宽高，等等诸如此类

解决： 虽然QuestPDF的链式写法，可以很方便的应对各种"花样"配置，但这些东西多了以后还是不可避免的陷入俗套，因此配置 JSON 规则时，最好是有一个有好的编辑器，我在系统里是集成了微软的Monaco编辑器，这是vs code同源的编辑器，可以快速的检查拼写错误，当然也可以在外边编辑器编写完成后在拷贝会系统，但这对非开发人员来说可能不太友好；

{
    "type": "GridForm",
    "title": "五、项目申报单位意见",
    "columnsCount": 10,
    "rows": [
        {
            "minHeight": 120,
            "cells": [
                {
                    "text": "项目申报单位负责人（签名）：\n\n\n单位公章：",
                    "colSpan": 10,
                    "style": {
                        "align": "left",
                        "verticalAlign": "top"
                    }
                }
            ]
        }
    ]
}

五、 最终效果与架构集成

现在，我们的流程变成了这样：

1. 管理层，Blazor Server: 给不同活动配置打印表格式
2. 服务层，PDF Service: 读取给不同活动配置的JSON规则和业务数据。
3. 服务层，Engine: 动态组装文档。
4. 展示层，Preview & Download: 服务端提供友好的预览操作，同理到webapi端，则根据用户的实际申报数据，生成pdf文件返回一个文件流到客户端。

六、 结语

从"动态表单定义"到"动态报表输出"，总算是闭环了一趴。

构建这个引擎虽然在初期比 HTML 方案多花了几天时间，但收益是巨大的：现在用户再提出一个新的活动打印需求，我只需要花少量的时间来编写一个 JSON 配置文件（这是后续唯一的"开发"成本，事实上JSON的内容非常有规律，即便不是专业开发，经过简单的培训也能书写一个专业的配置文件），不需要改动一行后端代码，也不需要重新发布服务。

把不确定性封装在配置里，把确定性留在代码里。这也许就是后端开发的乐趣所在吧。

最后我想说，我们总是听到一些科学家或者研究人员在接受采访时，轻描淡写的说一句"我们试了很多种方案"之类的话，可能只有亲身经历者才明白这句话背后的付出到底有多少吧。

这是我"从零构建动态表单引擎"系列的第二篇分享，后续再有其他积累再继续分析