---
url: https://qiwuadmin.com/features/formkit.md
description: 拖拽设计表单：可用的基础、业务和计算组件，天数与明细表合计的计算规则，导出 JSON 和 Vue 代码，以及保存时的安全白名单检查。
---

# 表单设计器

用拖拽的方式设计表单，不需要写代码。设计器基于开源的 form-create 设计器（MIT 协议），界面语言跟随系统语言，切换中英文后立即生效。

![表单设计器](/screenshots/zh-formkit.webp)

同一个设计器出现在三个地方：

| 位置 | 用途 |
| --- | --- |
| **系统工具 → 表单构建** | 设计、预览、导出代码。这里**不保存**表单 |
| **流程审批 → 流程管理 → 表单管理** | 设计并保存审批用的表单，见[工作流 · 动态表单](/features/workflow#动态表单) |
| **流程审批 → 流程管理 → 新建审批** | 向导的第 2 步"表单设计"，见[零代码审批](/features/workflow#零代码审批) |

::: tip 谁能看到这些菜单
"表单构建"没有按钮权限，在 **系统管理 → 角色管理** 里给角色分配这个菜单就能看到。表单管理和新建审批默认只有超级管理员能用，因为保存的表单就是一段会在别人浏览器里运行的配置。
:::

## 可以用的组件

左侧的组件列表分三组。

**基础组件**（15 个）：输入框、多行输入框、密码输入框、计数器、单选框、多选框、选择器、开关、评分、时间、时间区间、滑块、日期、日期区间、级联选择器。

**业务组件**（项目自己的组件，和后台其他页面用的是同一套）：

| 组件 | 保存的值 | 说明 |
| --- | --- | --- |
| 人员选择 | 用户 id | 输入框加选择弹框，列出所有启用的用户，普通员工也能选 |
| 部门选择 | 部门 id | 部门树，列出所有启用的部门，不受数据范围限制 |
| 字典选择 | 字典项的值（多选时是数组） | 在设置里选一个字典，比如"请假类型"。提交时服务端会核对这个值是不是启用的字典项 |
| 附件 | 每行一个文件 | 上传为**私有文件**，可以设置最多文件数（1–50）、单个文件大小上限和允许的文件类型 |
| 地区选择 | 地区编码路径，比如省、市、区三级 | 省市区三级选择（地区名称只有中文） |

**计算组件**：

| 组件 | 作用 |
| --- | --- |
| 天数（自动计算） | 只读的数字框，根据开始日期和结束日期算出天数，见下文 |
| 明细表 | 可以添加、删除行的表格，数字列在底部自动合计，见下文 |

没有出现在列表里的组件（颜色选择、穿梭框、树、富文本、手写签名、子表单、布局和辅助类组件等）是被有意隐藏的：它们要么需要运行代码，要么保存时会被安全白名单拒绝。设计器自带的"上传"也被隐藏了，附件统一用上面的"附件"组件。

因为没有布局组件，表单是平铺的，每个字段独占一行（可以单独设置标签宽度）。

## 计算组件

### 天数（自动计算）

在设置里填写"开始日期字段名"和"结束日期字段名"，它们必须是本表单里的单日日期组件。算法：

* 开始和结束这两天**都算在内**，比如 3 日到 5 日是 3 天；
* 可以再指定"开始上午/下午字段名"和"结束上午/下午字段名"（这两个字段的值是 `am` 或 `pm`）：下午开始减半天，上午结束减半天，这样就能请半天假；
* 不扣除周末和节假日；
* 缺少日期，或者结束早于开始时，结果为空。

### 明细表

在设置里编辑表格的列：列名、标题，以及"合计字段名"。填了合计字段名的列就是数字列，它的合计显示在表格底部，同时写入合计字段名指定的字段。

* 最多 20 列、100 行，文字单元格最多 500 个字符；
* 空行会自动去掉；
* 合计字段是一个数字字段，可以用作审批流程的分支条件，比如"报销金额超过 5000 元时增加一级审批"。

::: info 计算结果以服务端为准
用在审批表单里时，天数和合计在发起、审批时修改、重新提交时都会由服务端**用同一份代码重新计算**，覆盖浏览器提交的值。所以即使有人改了浏览器里的数字，分支条件也只会按真实的天数和金额走。
:::

## 导出 JSON 和 Vue 代码

设计器上方的"导出"按钮会打开一个对话框，里面有两个文件，可以复制或下载：

* **`form.json`**：表单的结构（字段规则和表单选项）；
* **`form.vue`**：一个 Vue 单文件组件，用 form-create 和项目的业务组件渲染这个表单。

导出的是经过安全白名单过滤后的内容，也就是保存时会留下的内容。表单里有不允许的设置时，会提示"表单无法导出"并说明原因。

`form.vue` 依赖项目前端的路径别名和业务组件，所以要放进本项目 `apps/web/src/views/` 下使用。它只负责显示表单，**不包含提交逻辑**：你需要读取表单数据，再调用自己的接口。

## 安全

表单结构会在别人的浏览器里渲染，所以它被当作代码来对待：

* 设计器里所有会执行用户输入的入口都被隐藏，包括组件事件、联动规则、自定义属性、JSON 编辑、函数校验和远程加载选项。前端页面使用严格的内容安全策略（CSP，不允许 `eval`），这些功能本来也无法运行；
* 保存时，前端和服务端用**同一份白名单**检查整个表单结构：
  * 包含函数或者会被当作代码执行的字符串（比如以 `$FN:` 开头的值）、事件和联动类的设置、未知的组件时，**直接拒绝**，返回 400 并说明是哪个字段；
  * 白名单以外的普通设置会被去掉。在表单管理里保存时，页面会先列出这些设置让你确认；新建审批向导会直接去掉，不提示；
  * 服务端只保存过滤后的结果；
* 一个表单最多 200 个字段，每个选项列表最多 500 项；字段名只能用字母、数字和下划线，并且以字母开头，不能重复。

更多安全措施见[安全基线](/features/security)。
