核心概念

Umo Editor Next 的文档表单能力可以概括为三类核心能力，它们通常不是互相替代，而是组合使用。

本页重点

1. 文档表单的三类核心能力分别是什么
2. design / fill / result / autofill 四种模式怎么理解
3. result、autofill、fillFormValues() 的使用边界是什么
4. 为什么需要富文本变量，以及它的风险边界是什么

三类核心能力

一、模板设计

模板设计面向“模板制定人”或“业务规范维护人”。

它的目标不是让最终填写人自由编辑全文，而是先把文档骨架设计好，像表单一样预先定义“哪些内容需要被填写”。

典型做法

• 在正文中插入变量，占位姓名、部门、日期、金额、项目、说明等信息
• 为变量设置名称、唯一键、描述、必填状态、日期格式、选项列表等属性
• 把合同、通知、报告、审批单等标准文档做成可复用模板

这一能力解决的是：

• 标准模板反复搭建的问题
• 多人起草时格式不一致的问题
• “哪些地方允许改、哪些地方不能改”不清晰的问题

建议与这些能力组合：

• 模板管理：模板分类、读取、维护
• 内容锁定：锁定固定条款或固定段落
• 文档修订：模板迭代时保留修改痕迹

二、程序填充

程序填充面向“业务系统”或“后端服务”。

它允许系统把外部变量值传入文档模板，自动生成不同内容的结果文档，而不是让前后端再自己去拼接大段 HTML 或字符串替换。

典型做法

• 后端根据订单、申请单、审批流、CRM、HR、ERP 数据生成正式文档
• 同一份模板，按不同用户、部门、项目、客户生成不同内容
• 在批量通知、协议生成、证明开具场景中自动出文
• 与 Umo Editor Next 的导出能力串联，在生成后继续批量输出 Word、PDF 等交付文件

这一能力解决的是：

• 字段替换链路分散，模板与程序逻辑割裂的问题
• 复杂排版文档不适合靠字符串替换维护的问题
• 同类文档批量生成效率低的问题
• 批量出文时版式不统一、导出链路分散的问题

程序填充主要通过两种方式接入：

1. 初始化时配置 form.mode: 'autofill' 与 form.values
2. 在确实需要运行时重新生成结果时，再调用实例方法 fillFormValues(values, options)

当使用程序填充模式时，编辑器会基于模板变量生成最终内容；对于未填充的变量节点，会在最终产物中移除，避免占位符泄露到正式文档。

如果你的业务是“批量出正式文件”，推荐把这条链路继续向后串起来：

1. 用模板定义文档骨架与变量位
2. 按业务数据优先初始化 form.values
3. 得到每一份生成后的正式内容
4. 在需要运行时重新生成结果时，再调用 fillFormValues()
5. 继续结合 Umo Editor Next 的导出能力，批量导出 Word、PDF 或图片

这样可以把“模板设计、变量填充、结果导出”统一在同一套文档模型里，避免模板和导出链路分裂。

三、表单能力

表单能力面向“人工填写与结果校验”。

它允许最终填写人在右侧表单面板中按字段输入内容，同时复用变量定义中的规则，保证填写结果尽可能正确、完整、可提交。

核心能力包括：

• 必填约束
• 变量类型对应的规则校验
• 自定义类型规则扩展
• 结构化数据收集
• 提交结果回调
• 获取当前填写值与变量定义

这一能力解决的是：

• 漏填、错填、格式不合规的问题
• 文档里“可填字段”不集中，填写成本高的问题
• 填写完成后无法把字段值直接回收到业务系统的问题
• 最终提交时无法拿到结构化变量数据的问题

这里的“表单能力”除了校验与提交，还有一个很核心的作用，就是数据收集能力。

也就是说，文档表单不只是把变量显示在页面上让人填写，更重要的是在填写完成后，把这些字段按结构化方式回收到业务系统中。这样业务侧就可以直接拿到：

• 当前变量值
• 变量定义
• 最终文档内容

然后继续用于：

• 保存草稿或正式记录
• 发起审批流
• 做台账沉淀
• 做统计分析或报表汇总
• 作为后续程序填充、版本留存、归档的基础数据

四种工作模式

当前公开能力可以理解为以下四种模式：

design 模式

• 编辑器正文可编辑
• 适合插入变量、设置变量属性、维护模板结构

在 design 模式下，有两个很实用但容易被忽略的点：

• 文本类变量支持格式设置：文本变量不是只能显示一个朴素占位符。它会保留插入位置的行内格式，结果生成时也会沿用这些格式。因此你可以像编辑普通正文一样，为变量设置加粗、斜体、下划线、颜色、背景高亮等样式。
• 图片类变量支持属性设置：图片变量除了 name / key / description / required 之外，还可以继续设置宽高、自适应高度、等比缩放、浮动拖拽等属性；stamp 变量还支持常用尺寸预设。

这意味着文档表单并不是“只有字段，没有表现层”。模板制定人可以在设计阶段同时确定：

• 字段值的业务语义与校验边界
• 字段在正文中的呈现方式
• 图片变量在版面中的尺寸与占位方式

对于合同、申请单、回执单、盖章页、签字页这类正式文档，这一点尤其重要，因为它直接影响最终成文效果，而不只是填写体验。

fill 模式

• 编辑器正文不再用于自由编辑
• 由填写人在表单面板中输入变量值
• 支持校验、提交、重置、图片类变量上传
• 特别适合“收集字段值 + 回传结构化数据”的业务录入场景

result 模式

• 根据当前变量值把正文渲染成结果态
• 适合预览或只读查看最终填写结果

它更适合：

• 审批前查看最终结果
• 生成后只读展示
• 不允许继续录入、只允许查看结果的业务页面

autofill 模式

• 面向系统自动生成
• 常规场景优先结合 form.values 批量传值
• 在运行时需要切换数据并重新生成结果时，再使用 fillFormValues()
• 更适合作为“模板 -> 最终文档”的生成链路，而不是人工录入界面

结果生成相关能力怎么区分

设计态预览与结果态的关系

在设计模板时，工具栏里的“预览”更适合用于快速检查模板在填写态下的展示效果，例如：

• 变量区是否布置合理
• 右侧表单项是否齐全
• 必填项、说明文案、字段顺序是否符合预期

它适合做模板设计阶段的快速核对；而 result 模式更适合在已有变量值的前提下，查看最终结果文档。

富文本变量的定位

富文本变量存在的主要目的，是为了让程序填充可以插入复杂结构内容，例如：

• 表格
• 多段落说明
• 带格式的条款正文
• 列表、标题、引用块等结构化内容

这让一个模板不只能够替换简单文本，还能在局部区域注入复杂排版内容。

它的设计初衷，本质上是为了弥补固定节点类型的表达边界。

普通变量更适合承载这类内容：

• 一个姓名
• 一个日期
• 一个金额
• 一个选项值
• 一张图片

但在很多真实业务里，程序需要动态生成的并不是“一个值”，而是一整段结构化内容。例如：

• 明细表格有多少行并不确定
• 表格中的每一行数据都可能来自循环生成
• 某个章节下要按条件生成多段说明
• 某些条款、列表、附件说明需要按业务数据动态拼装

这类内容如果强行拆成多个普通变量，通常会遇到几个问题：

• 模板维护成本很高
• 节点数量和结构无法提前固定
• 数据循环、条件分支和复杂排版很难自然表达

因此富文本变量更像是一个“复杂内容插槽”：

• 普通变量负责简单值替换
• 富文本变量负责承接普通变量难以表达的复杂结构生成

在一些复杂程序出文场景里，例如动态生成表格、循环生成条目明细、按条件输出章节内容，富文本变量往往是更合适的选择。

为什么不建议让用户手工填写富文本变量？

虽然富文本变量也能出现在填写链路中，但它本身存在更高的不确定性：

• 输入内容可能包含复杂嵌套结构
• 不同来源内容的格式兼容性难以完全可控
• 结果可能影响周边排版或生成稳定性

因此更推荐的原则是：

• 人工填写场景：优先使用文本、数字、日期、选项等可控类型
• 程序填充场景：在确有需要时使用富文本变量，由后端或可信内容源生成

如果富文本变量内容无法被当前编辑器文档模型安全接纳，程序填充链路会通过 form.onFillError(errors, context) 给出错误信息，便于业务侧兜底处理。

与其他功能联动的推荐顺序

如果你的目标是“模板长期维护 + 业务生成 + 对外交付”，推荐按下面的顺序组织链路：

1. 用 design 模式设计模板
2. 通过模板管理管理模板版本与入口
3. 用内容锁定保护固定骨架
4. 人工填写时切到 fill，程序生成时切到 autofill
5. 结果确认后结合导出输出最终稿
6. 模板维护过程结合修订与历史版本沉淀变更过程