为什么需要前端做模板编译

这个项目里有一个看似矛盾的地方：编辑器给使用者展示的是可视化的富文本，但最终要交给后端的却是 FreeMarker 模板。

说白了使用者在页面上看到的是“投保人姓名”这样的蓝色标签。保存下来的是带 data-variable 属性的 HTML，最终生成的却是 ${info.insuredName!} 这样的 FTL 表达式。

中间这个转换过程，一开始是打算让后端来做的。但后来发现几个问题：

• 编辑器里的变量样式、边框容器、页眉图片这些结构信息，传到后端再解析很容易丢细节。
• 业务人员在编辑器里操作完之后需要马上看到生成的模板效果。如果每次都走后端，响应太慢。
• 模板的校验规则放在前端能更早发现问题，减少无效提交。

使用者痛点：样式丢失导致文档排版错乱、生成延迟影响业务审批效率、缺乏即时校验导致反复修改。

最终决定在前端做一个完整的模板编译层，把 HTML 转换成 FTL。

两阶段转换管线架构

整个转换过程不是一步到位的，而是分成了两个阶段：

阶段一：原始文档 → 带 {{变量方法}} 标记的 HTML
再看阶段二。带标记的 HTML → 完整 FTL 模板

阶段一是在编辑器内部完成的。当使用者点击“生成”按钮时getGenerateContent 会调用 convertVariablesForGenerate把编辑器里的变量节点转换成 {{prop}} 或 {{prop||styleStr}} 这样的占位符。话说回来，这一步主要是把可视化的节点变成字符串标记，方便后续处理。

阶段二就是 ftlGenerator.ts 做的事情。它拿到带标记的 HTML，经过词法分析、语法分组、代码生成、结构适配等步骤。最终输出完整的 FTL 模板。

这个两阶段的好处是职责清晰：阶段一只负责“把编辑器内容转成标记”，阶段二负责“把标记编译成模板”。它们之间逻辑，

从词法分析来看。变量标记的提取与分类

编译的第一步先是词法分析，也就是从 HTML 中找出所有变量标记，并给它们分类。

变量提取

代码里用了一个正则表达式来提取所有 {{prop}} 和 {{prop||styleStr}} 格式的标记：

const regex = /\{\{)?其实，\}\}/g

这个正则匹配以 {{ 开头、}} 的字符串。第一组捕获变量方法，第二组捕获可选的样式字符串。

建立映射表

User Pain Point: 没有映射表时数组字段难以定位，会导致循环代码生成错误。

`buildArrayMap`

export const buildArrayMap = : Map => {
const map = new Map
const traverse = => {
for {
if {
for {
const fieldName = child.value.split.pop || child.value
map.set(child.value,{
arrayPath: opt.value。fieldName
})
}
}
if {
traverse
}
}
}
traverse
return map
}

`buildDynamicMap`

export const buildDynamicMap = : Map => {
const map = new Map
const traverse = => {
for {
if ) {
map.set
}
if {
traverse
}
}
}
traverse
return map
}

变量分类

有了映射表之后每个变量标记就可以被分类了。 代码里定义了三种 MatchType{'array'|'dynamic'|'normal'}：

type MatchType = 'array' | 'dynamic' | 'normal'

• `array`：数组类型变量，需要生成 <#list> 循环；
• `dynamic`：动态控制变量，如分隔符、序号、列表起止标记；
• `normal`：普通变量，直接转成 ${prop!}.

说到语法分组。从线性扫描到结构化分组

词法分析得到的是一个线性的变量列表，但模板里的数组变量必须被归为同一个循环块，这就需要语法分组。

两种分组类型

动态列表栈匹配

连续数组自动归组

从代码生成来看，FTL 模板的组装

# 数组组生成逻辑

• `array` 变量转为 ${info.fieldName!}
• `dynamic.N`使用 FreeMarker 数组表达式：
• `wrapWithStyle` 用于样式透传：

# 单变量处理

• `normal` → `${prop!}`，
• `dynamic` → 实际字符；
• `dynamic.N` 在非循环上下文中直接忽略。
.

HTML 结构适配

# DOMParser 解析

# 边框容器转 table

# 页眉容器转三列 table 布局

# 分页标记注入 page-break-before

# 包装完整骨架

再看校验层，发布前静态检查

The compiler includes a validation step that checks wher dynamic list markers are correctly paired before publishing.

ts

export

User Pain: Unmatched ListS/ListE markers cause runtime errors and hard‑to‑debug PDF generation failures.

typescript

...

**Key Takeaways**
• Two‑stage pipeline separates UI concerns from compilation logic.
• Lexical → Syntax → Code generation mirrors classic compiler design.
• HTML structure adaptation guarantees that generated template renders correctly across environments.
• Static validation catches errors early—saving time for business users and developers alike.

This architecture bridges gap 娱乐ween visual editing experience and robust FreeMarker template output。delivering a fast‑feedback loop while preserving layout fidelity and reducing maintenance overhead.