🎉🎉🎉 移动端文档编辑器 Umo Editor Mobile 现已发布，了解更多 →
开发文档Umo Editor Next文档表单配置项

配置项

文档表单能力的配置入口为 options.form。

阅读建议

如果你是第一次配置，建议优先关注这几项：

  • form.mode：先决定当前页面是设计、填写、展示还是程序出文
  • form.values：决定初始值、回填值和程序填充值
  • form.types：扩展业务校验规则
  • form.onSubmit / onSubmitted / onFillError：接入提交、通知和异常兜底

配置速查

配置项主要作用什么时候最先看
form.mode决定当前工作模式刚开始接入时
form.values提供初始值、回填值、填充值做回填、补填、程序出文时
form.types扩展业务规则类型内置校验不够用时
form.finalContentFormat决定最终内容返回格式需要落库、导出或文本处理时
form.onSubmit接管人工填写提交做人工填写时
form.onSubmitted监听提交流程结束提交后需要跳转、提示、上报时
form.onFillError接管程序填充异常做富文本填充或批量出文时

配置示例

const defaultOptions = {
  form: {
    enabled: true,
    mode: 'fill',
    values: {},
    types: {},
    finalContentFormat: 'json',
    async onSubmit(result, context) {},
    async onSubmitted(status, payload) {},
    async onFillError(errors, context) {},
  },
}

配置项说明

form.enabled

说明：是否启用文档表单能力。

类型：Boolean

默认值：false

详细说明：

  • 这是文档表单能力的总开关
  • 关闭后，模板设计、人工填写、程序填充、变量面板、表单提交等整条链路都不会启用
  • 只有在 form.enabled = true 的前提下，form.mode、form.values、form.types、form.onSubmit 等配置才有意义

什么时候开启：

  • 你要把正文做成“带变量位的模板”时
  • 你要收集结构化字段值时
  • 你要按变量批量生成文档时

相关页面：

form.mode

说明：表单运行模式。

类型：String

可选值：

  • design：模板设计模式
  • fill：人工填写模式
  • result：结果查看模式
  • autofill：程序填充模式

默认值：design

使用建议：

  • design：模板制定人设计变量与模板结构
  • fill：面向填写人收集字段值
  • result：面向结果查看、只读展示、导出前确认
  • autofill：面向后端或业务系统批量生成结果文档

其中 result 更偏“展示当前结果”，autofill 更偏“程序自动出文”。

详细说明：

  • mode 决定了当前页面的工作目标，而不只是界面展示差异
  • 同一份模板，在不同模式下可以承担完全不同的职责：
    • 在 design 下负责定义模板和变量
    • 在 fill 下负责人工录入和校验
    • 在 result 下负责结果展示
    • 在 autofill 下负责程序生成
  • 如果模式选错，通常会导致“能展示但不能提交”“能生成但不能继续编辑”这类接入误解

选型建议：

  • 先问自己当前页面的目标是什么，再选模式
  • 如果是“先让人填”，优先看 fill
  • 如果是“页面一打开就自动成文”，优先看 autofill
  • 如果是“只展示结果”，优先看 result

相关页面：

form.values

说明：变量值对象。

类型：Object

默认值：{}

values 的 key 应与变量取值键对应。不同类型的值建议如下：

  • 文本 / 数字 / 日期 / 单选 / 下拉：String 或 Number
  • 日期范围 / 时间范围 / 多选：Array
  • 图片类变量：String（图片 URL）或 Object
  • 富文本变量：合法的 Tiptap HTML 或 JSON 片段。

图片类变量对象可包含这些字段：

{
  url: 'https://example.com/image.png',
  name: '附件图片',
  size: 1024,
  type: 'image/png',
  content: null,
  width: 300,
  height: 160,
}

在用户填写阶段，form.values 的作用同样很重要。它会在 fill 模式下作为表单初始值参与运行时状态构建，既用于首次回显，也用于重置时恢复默认值。

因此它特别适合：

  • 草稿恢复
  • 历史填写结果回填
  • 驳回后重新编辑
  • 系统预填部分字段后交给用户补充

如果不传 form.values，填写人通常会从空白状态开始输入；如果传入了对应字段值，右侧表单面板会优先展示这些已有值。

需要注意的是，form.values 更接近“初始化值 / 默认值来源”。用户在填写过程中的修改，会进入运行时表单状态与提交结果中；如果业务侧希望长期保存这些变化，应在 form.onSubmit、form.onSubmitted 或 onSave 中自行回收并持久化。

如果页面目标是直接查看生成后的结果，通常也会配合 form.mode = 'result' 或 form.mode = 'autofill' 一起使用。

详细说明：

  • form.values 是整条表单链路里最重要的输入之一
  • 它既可以表示“程序填充值”，也可以表示“填写默认值”或“历史回填值”
  • 在 fill 模式下，它会影响：
    • 首次回显
    • 草稿恢复
    • 驳回补填
    • 重置后的恢复值
  • 在 autofill 或 result 模式下，它会直接参与结果内容生成

接入建议：

  • 正式业务中，优先按稳定的变量 key 传值
  • 做初始化即出文时，优先通过 form.values 传入数据
  • 只有在实例创建后还要按新数据重新生成时，再考虑 fillFormValues()

相关页面：

  • 快速开始：查看 fill 和 autofill 下的最小示例
  • 方法列表：查看和 fillFormValues() 的分工关系
  • 字段设计：了解稳定 key 和值形态设计
  • 排障指南：排查值形态、key 不匹配、图片/富文本填充异常

form.types

说明：自定义变量类型配置，用于扩展变量面板中的可选规则类型与校验规则。

类型：Object

默认值：{}

目前支持以下分组键：

  • text
  • number
  • date
  • radio
  • checkbox
  • select
  • richtext

每个分组的值为数组，数组项结构如下：

{
  type: 'contract_code',
  text: {
    zh_CN: '合同编号',
    en_US: 'Contract Code',
  },
  rules: [
    {
      pattern: /^HT-\d{6}$/,
      message: {
        zh_CN: '合同编号格式不正确',
        en_US: 'Invalid contract code format',
      },
    },
  ],
}

对于图片类变量，实际接入时建议至少提供 url。如果还需要在下载、展示或回填时保留更多文件信息，再补充 name、size、type、width、height 等字段。

富文本变量虽然支持复杂内容，但更推荐由后端或可信内容源生成。如果传入内容无法被当前文档模型接纳，程序填充阶段会通过 form.onFillError 暴露异常信息。

其中：

  • type：规则类型标识
  • text：面板显示文案，支持字符串或多语言对象
  • rules：校验规则数组

使用场景：

  • 企业内部字段规范化
  • 统一手机号、编号、日期、金额等规则
  • 让模板制定人直接在面板中选择业务规则

这项能力特别适合：

  • 企业内部有统一字段规范，需要多个模板共用同一套校验规则
  • 不同行业存在固定编码格式，例如合同编号、病例号、学号、工号、客户编号
  • 希望把校验逻辑前置到模板设计阶段，而不是等提交后再由后端报错

详细说明：

  • form.types 不是新增一种基础变量节点，而是给现有变量类型补充“可选规则类型”
  • 它的价值在于：让模板制定人不需要手写正则，而是直接选择业务已经约定好的规则
  • 这样可以把“校验规则”从零散代码里抽出来，收口成统一的模板能力

什么时候适合引入：

  • 多个模板都要共用同一套字段规则
  • 业务字段有稳定格式，例如合同号、病例号、员工编号、客户编号
  • 想让模板制定人自行配置规则，但又不希望每次都改代码

如何自定义校验规则：

最常见的做法，是按变量分组为 form.types 追加规则类型：

const defaultOptions = {
  form: {
    enabled: true,
    types: {
      text: [
        {
          type: 'patient_no',
          text: {
            zh_CN: '病例号',
            en_US: 'Patient No.',
          },
          rules: [
            {
              pattern: /^MR-\d{8}$/,
              message: {
                zh_CN: '病例号格式应为 MR-20260729',
                en_US: 'Patient No. must be like MR-20260729',
              },
            },
          ],
        },
      ],
    },
  },
}

文档表单的校验规则复用了 TDesign Vue Next Form 的能力，因此如果你希望快速扩展更多规则，最直接的参考资料就是 TDesign 官方表单文档：https://tdesign.tencent.com/vue-next/components/form

如果你需要更稳的模板维护体验，建议把常用规则抽成统一命名的类型，例如：

  • contract_code
  • employee_no
  • patient_no
  • invoice_amount

这样模板制定人不需要记正则，只需要在变量面板中直接选择规则类型。

相关页面：

  • 快速开始：查看自定义校验规则的最小示例
  • 字段设计：先设计对字段类型，再补规则
  • 排障指南：排查规则不生效、值类型不匹配等问题

form.finalContentFormat

说明：最终内容返回格式。

类型：String

可选值：all、auto、html、json、text

默认值：auto

行为说明：

  • html：只返回 HTML
  • json：只返回 JSON
  • text：只返回纯文本
  • all：同时返回 html / json / text
  • auto：优先跟随 document.contentType，若不是 html / json / text，则回退为 json

使用场景：

  • 后端继续落库存结构化内容：推荐 json
  • 对接现有 HTML 模板链路：推荐 html
  • 需要全文检索、摘要或文本审核：可用 text

详细说明：

  • 这个配置决定了“提交结果”或“程序生成结果”里，最终文档内容按什么格式返回
  • 它不会改变模板本身的编辑方式，而是影响结果数据如何交给业务系统继续使用
  • 如果你后续还要做：
    • 结构化落库
    • 二次处理
    • 文本审核
    • 对接其他内容服务 那么这里的格式选择就很重要

选择建议：

  • 不确定时，优先用 json
  • 已有 HTML 渲染链路时，再考虑 html
  • 做纯文本检索、摘要、敏感词检测时，再考虑 text

相关页面：

form.onSubmit

说明：人工填写模式下的提交回调。

类型：Function | Async Function | null

默认值：null

参数：

  • result：当前提交结果对象
  • context：表单提交上下文

当前 result 的主要字段包括：

  • values：当前填写结果，默认只保留非空项
  • definitions：变量定义列表
  • finalContent：按 finalContentFormat 生成的最终文档内容
  • valid：当前是否通过校验

definitions 中每一项会包含：

  • id
  • type
  • ruleType
  • format
  • separator
  • name
  • key
  • description
  • required
  • options
  • defaultValue
  • value
  • props

返回值：

建议返回：

{
  success: true,
  message: '提交成功',
}

或：

{
  success: false,
  message: '提交失败原因',
}

使用场景：

  • 把填写值提交到后端
  • 回收结构化字段数据
  • 发起审批流
  • 保存草稿或正式结果
  • 触发业务校验后的二次处理

详细说明：

  • onSubmit 是人工填写链路里最核心的对外出口
  • 它不是只返回一个“是否提交成功”的状态，而是一次性把：
    • 当前填写值
    • 当前变量定义
    • 当前结果文档 一并交给业务侧
  • 因此它非常适合承担“表单提交 + 数据回收 + 文档结果回收”的统一入口

接入建议：

  • 如果只是人工填写场景，优先围绕 onSubmit 设计业务提交流程
  • 不要把“读取字段值”和“获取最终结果”拆成多套并行逻辑，尽量在这里统一收口

相关页面：

  • 快速开始：查看人工填写最小示例
  • 方法列表：查看 result.values / result.definitions / result.finalContent 的使用方式
  • 使用场景：查看审批、登记、采集、病历等提交类场景

form.onSubmitted

说明：onSubmit 结束后的通知回调。

类型：Function | Async Function | null

默认值：null

参数：

  • status：success 或 error
  • payload：提交结束时的附加数据

当前链路下，payload 至少会包含：

  • result：本次提交的结构化结果

并根据提交结果附带以下其中之一：

  • submitResult：onSubmit 的返回值
  • error：onSubmit 抛出的错误对象

使用场景：

  • 成功后跳转页面
  • 成功后刷新业务列表
  • 失败后上报日志或弹出业务提示

详细说明：

  • onSubmitted 更适合承担“提交结束后的后置动作”
  • 它不负责生成提交结果，而是用来根据提交成败做界面反馈或业务联动
  • 可以把它理解为：
    • onSubmit 负责真正提交
    • onSubmitted 负责提交完成后的通知与收尾

推荐用途：

  • 成功后跳转详情页或列表页
  • 成功后关闭弹窗、刷新数据、给出成功提示
  • 失败后上报日志、记录埋点、弹出统一错误提示

相关页面：

  • 快速开始：查看 onSubmit / onSubmitted 的最小接入方式
  • 方法列表：查看人工填写链路推荐组合

form.onFillError

说明：程序填充链路的错误回调。

类型：Function | Async Function | null

默认值：null

参数：

  • errors：错误列表
  • context：本次填充上下文

根据当前实现，errors 数组中的错误项会包含：

{
  code: 'invalid-richtext-content',
  key: 'variable_key',
  item: {},
}

context 中会包含：

  • values：本次传入的变量值
  • format：本次生成格式
  • disableForm：是否在生成后关闭表单态
  • sourceContent：填充前的原始文档内容
  • invalidItems：无效变量项列表
  • filledContent：本次生成结果

使用场景：

  • 富文本变量内容不合法时告警
  • 生成前后做兜底回退
  • 上报程序填充失败日志

详细说明：

  • onFillError 是程序填充链路的异常出口
  • 当前最需要重点关注的，是富文本变量内容不合法这类情况
  • 如果你的业务涉及：
    • 富文本插槽
    • 动态表格
    • 批量出文
    • 服务端拼装复杂内容 那么建议把它当成正式能力接入，而不是调试日志

推荐用途：

  • 记录批量出文失败项
  • 遇到异常时回退模板或降级为普通文本
  • 给运维、日志平台、业务监控系统上报告警

相关页面：

内置类型能力

内置规则类型已经覆盖一批常见业务字段，例如：

  • 文本类：网址、邮箱、手机号、身份证号、中文姓名、邮编、车牌号、银行卡号、统一社会信用代码、短横线分割的字符串
  • 数字类：正整数、非负整数、整数、两位小数、百分比、年份、月份、日期
  • 日期类：日期、日期区间、时间、时间区间

如果这些内置规则还不够，可以通过 form.types 补充业务私有类型。

富文本变量的配置建议

富文本变量更适合服务端或可信内容源生成复杂结构内容，例如表格、说明块、条款正文。

它存在的主要意义，不是把“普通输入框”升级成“可编辑大文本”，而是弥补普通变量在复杂结构生成上的不足。例如：

  • 需要按循环动态生成不定行数的表格
  • 需要按业务数据动态输出多段说明
  • 需要在一个变量位里承接列表、标题、引用块等组合结构

这类场景下，如果只靠文本、数字、日期、选项等普通变量，通常很难自然表达。

不建议把它作为普通用户的自由填写项。更推荐的做法是：

  • 人工填写：优先使用文本、数字、日期、选项类变量
  • 程序填充：确有必要时使用富文本变量，并配合 onFillError 做异常兜底
核心概念方法列表