变量类型与字段设计
文档表单能不能真正稳定落地，关键不只在“能不能插变量”，更在于模板设计阶段有没有把字段语义、命名规则、值形态和风险边界提前收口。
本页重点
- 先选对变量类型，再谈校验规则
name / key / description / required这四个字段要先设计稳- 模板设计阶段的字段约束，决定后续填写、程序填充和导出是否稳定
选型速查
| 如果你要表达的是 | 更推荐的类型 |
|---|---|
| 姓名、标题、简短说明 | text |
| 金额、数量、比例 | number |
| 日期、时间、区间 | date |
| 固定单选项 | radio / select |
| 固定多选项 | checkbox |
| 复杂表格、复杂段落、动态章节 | richtext |
| 图片、签名、印章、二维码 | 图片类变量 |
这一页重点回答三个问题：
- 应该选什么变量类型
- 字段的
name / key / description / required应该怎么设计 - 后续人工填写、程序填充、导出时，什么样的字段设计更稳
一、先分清两类变量
当前实现，变量分为两大类：
文本类变量
支持的基础类型包括：
textnumberdaterichtextradiocheckboxselect
这类变量更适合承载：
- 姓名、部门、金额、日期、编号、说明
- 单选状态、多选项、下拉选项
- 局部复杂内容（富文本）
文本类变量也支持格式设置
这点非常重要：文本类变量不只是“有值就替换”的数据位，它还可以直接沿用正文里的行内格式。
根据当前实现，文本变量在插入和更新时会保留当前节点上的文本 marks，结果生成时也会继续把这些 marks 带到最终内容里。因此你可以把文本变量当成“带样式的动态文字”来设计，而不只是一个朴素占位符。
实际可直接利用的能力包括：
- 加粗、斜体、下划线、删除线
- 文字颜色、背景高亮
- 与周围正文一致的字号、字体、行内样式
最实用的场景包括：
- 合同标题中的动态字段需要和固定标题保持同样强调样式
- 金额、日期、风险提示字段需要高亮显示
- 通知、函件、证明等正式文档中，变量值需要和上下文保持统一版式
需要区分的是：
- 正文样式：直接在文档里像普通文字一样设置，适合控制变量最终显示效果
- 字段规则：在右侧变量面板里设置，适合控制校验、日期格式、区间分隔符、选项等行为属性
也就是说，文本变量既支持“值的约束”，也支持“值的展示格式”。
图片类变量
支持的基础类型包括：
imagesignaturestampqrcodebarcode
这类变量更适合承载：
- 图片附件
- 手写签名
- 印章
- 业务二维码
- 条形码
图片类变量支持属性设置
图片类变量也不只是“放一张图”这么简单。设计模式下，右侧变量面板除了基础字段外，还支持继续设置图片变量的属性。
当前可直接使用的属性设置包括：
- 宽度、高度
- 自适应高度
- 等比缩放
- 浮动拖拽
stamp变量的常用尺寸预设
这几个属性很实用，因为图片类变量往往直接决定版面观感。例如：
- 附件截图通常适合固定宽度 + 自适应高度，避免拉伸变形
- 签字位通常更适合较小尺寸，避免占用过多正文空间
- 盖章位通常需要固定视觉尺寸，方便模板提前预留版面
- 二维码、条码这类变量通常要明确控制尺寸，避免打印或扫码体验不稳定
从模板设计角度看，图片变量至少要同时考虑两件事：
- 它承载什么业务语义，例如附件、签字、印章、二维码
- 它在文档中应该以什么尺寸和占位方式出现
这也是为什么图片变量的“属性设置”在正式业务中很重要，它直接影响最终成文和导出效果。
二、优先按业务语义选类型
推荐顺序不是“能放进去就行”，而是“选择最贴近业务含义、最容易约束的类型”。
普通文本
适合：
- 姓名
- 部门
- 标题
- 简短说明
不适合：
- 明确需要数字计算的金额、数量
- 明确需要日期格式的字段
- 明确应从固定选项里选择的字段
数字
适合：
- 金额
- 数量
- 比例
- 年份、月份、天数
推荐优先使用内置规则类型而不是“普通数字”，例如：
- 正整数
- 非负整数
- 两位小数
- 百分比
这样可以把错误拦在填写阶段，而不是到业务提交后才发现。
日期
适合：
- 生效日期
- 申请日期
- 签署日期
- 起止时间区间
如果业务上是“单日期 / 日期区间 / 时间 / 时间区间”，建议直接按实际语义选，不要都用普通文本代替。
选项类：radio / checkbox / select
适合：
- 状态
- 类别
- 结论
- 标签
- 多项勾选
字段候选值固定时，优先使用选项类变量，不要让填写人手输。
富文本
适合：
- 程序生成的复杂表格
- 多段落说明
- 带格式的条款内容
不建议：
- 作为普通填写人的自由输入项
原因是富文本结构复杂，内容来源不稳定，后续程序填充、预览、导出时都更容易出现不可控情况。
图片类变量
适合：
- 用户上传的附件图片
- 签字确认
- 盖章
- 业务二维码、条码
如果业务语义明确，优先用对应类型，不要把所有图片都统一当作 image。
三、字段四要素怎么设计
在设计变量时，至少要明确这四个字段：
namekeydescriptionrequired
1. name：给人看的文案
name 决定：
- 正文里的变量展示文案
- 右侧表单面板中的标签文案
建议：
- 使用业务人员能立即看懂的名称
- 同一模板内避免多个“名称完全一样但含义不同”的字段
推荐示例：
- 合同名称
- 甲方名称
- 生效日期
- 审批意见
不推荐示例：
- 名称1
- 文本字段
- 说明内容
2. key：给程序看的稳定标识
根据当前实现，变量值优先按 key 读取，key 缺失时才回退到 id。因此在正式业务中，不要依赖自动生成的 id，应显式设置稳定的 key。
推荐原则：
- 一个字段只用一个稳定 key
- key 一旦对外使用，尽量不要随意改名
- 用业务语义命名，而不是 UI 命名
推荐风格：
contract_name
party_a_name
effective_date
approver_comment不推荐：
var_xxx
text1
fieldA3. description：填写说明与业务上下文
description 适合承载：
- 字段含义说明
- 填写来源说明
- 填写规则提示
推荐用法：
- “请填写营业执照上的企业全称”
- “格式为 YYYY-MM-DD”
- “若无补充说明可留空”
不要把校验规则全塞进说明里。能通过变量类型或规则表达的内容，优先用规则收口。
4. required：是否必填
是否必填，应该按“业务是否允许缺失”来定义，而不是按“这个字段通常会填”来定义。
推荐原则：
- 缺了就无法出正式文档的字段：设为必填
- 仅用于补充说明、可选备注的字段：不要设为必填
四、值形态设计规范
根据当前源码链路，不同变量类型对应的值形态建议如下。
文本 / 数字 / 单选 / 下拉
推荐传：
StringNumber
示例：
{
contract_amount: 12800.5,
party_a_name: '某某科技有限公司',
contract_status: 'approved',
}多选 checkbox
多选值应为数组。
示例：
{
notice_channels: ['email', 'sms'],
}如果传了非数组值，运行时不会按多选正确处理。
日期 / 日期区间
单日期建议传单值；日期区间、时间区间建议传长度为 2 的数组。
示例：
{
effective_date: '2026-07-29',
service_period: ['2026-08-01', '2027-07-31'],
}如果是区间字段但没有完整传入两端值，运行时会把它视为空区间。
图片类变量
图片类变量既支持直接传 URL 字符串，也支持对象。
推荐对象形态：
{
signature_image: {
url: 'https://example.com/signature.png',
name: '签名',
size: 10240,
type: 'image/png',
width: 300,
height: 120,
content: null,
},
}最低要求是必须有 url。如果没有 url，该值会被视为空。
富文本变量
当前链路允许富文本变量接收：
- 非空字符串
- 非空数组
- 非空对象
但这不代表“任何内容都能安全写入文档”。如果传入内容不能被当前编辑器文档模型安全接纳，程序填充时会进入 onFillError。
因此建议：
- 仅由可信程序生成富文本内容
- 在服务端预先约束结构
- 仅在确有复杂内容需求时使用
五、字段设计最佳实践
1. 一类业务字段，只定义一种数据语义
例如“合同金额”始终用数字字段，不要有的模板用文本，有的模板用数字。
这样后端更容易复用同一套传值逻辑。
2. key 要面向系统长期稳定
模板更新时可以改 name，但不要轻易改 key。否则：
- 历史回填会失效
- 程序填充映射会失效
- 下游保存的数据会断链
3. 能枚举就不要自由输入
例如审批结果、性别、是否签收、付款方式、部门类型等，优先使用选项类字段。
4. 能结构化就不要全塞到富文本
如果一个字段本质上只是日期、金额、编号、结论，就不要为了“灵活”塞进富文本变量。
5. 富文本只承接“复杂内容块”
推荐把富文本变量限制在：
- 报告说明区
- 程序生成表格区
- 条款块插入区
不要把整份文档的大量核心字段都塞进富文本。
6. 模板面向批量生成时，字段粒度要刚好
如果字段拆得过粗，程序不好复用；如果拆得过细，模板维护和传值成本会很高。
推荐原则：
- 对后端真实有独立数据来源的字段，单独拆变量
- 对始终一起出现、不会单独变化的文案，保留为固定模板正文
六、适合批量生成的字段设计
如果你的目标是批量生成 PDF / Word 正式文件，建议重点做到：
key稳定且语义清晰- 同类模板字段命名统一
- 数字、日期、选项等使用明确类型
- 富文本字段数量尽量少，只放必要复杂内容
- 固定正文与变量正文边界清晰
这样程序侧只需要准备变量值数据，就可以稳定复用同一模板批量生成不同结果，再继续走 Word / PDF 导出链路。
七、什么时候应该重构字段设计
出现下面这些现象时，通常说明模板字段设计需要回头调整：
- 后端总是要额外写一层字段转换
- 不同模板对同一业务字段用了不同 key
- 业务方经常分不清某个字段该填哪里
- 程序填充时大量字段需要拼字符串后再塞进富文本
- 导出后发现同类文档结构差异越来越大
这类问题越早在模板设计阶段收口，后续人工填写、程序填充、导出、归档就越稳定。