---
wide: true
---
# 设计器
`DouFormBuilder` 是可视化编辑表单描述的设计器。左边是字段面板和结构树,中间的画布是渲染器画出的表单,右边是选中节点的设置。它编辑的是和 `DouFormRenderer` 同一份描述,画布上看到的和最终渲染的一样。
## 基础用法
`v-model` 绑定表单描述。每次修改都会交出一份新的描述对象,没有改到的节点沿用原来的对象,所以可以直接比较引用判断某个节点有没有变。`v-model:selection` 绑定选中节点的 id 列表,不需要时可以不绑。
## 添加和选中
单击字段面板里的类型就会添加一个新节点:选中的是分组、列表或页面时加在它的末尾,选中的是标签页或分步时加在当前显示的那一页,否则加在选中节点的后面;什么都没选时加在表单末尾。新字段有不重复的字段名(如 `select1`),选项类字段先带三个选项,添加后自动选中,方便接着修改。
单击画布上的节点选中它。按住 ⌘ 或 Ctrl 单击可以加选或取消选中;按住 Shift 单击会选中上次单击的节点到这个节点之间的所有节点。单击表单以外的空白处选中表单本身。选中节点的右上角有操作按钮:选中上一级、上移、下移、复制、删除;节点较窄时收进“更多操作”菜单。标签页和分步的页签可以单击切换和选中,`+` 添加一页。
画布外的字段先用占位块代替,滚动到附近时才画出来,几百个字段的表单也能很快打开。
## 拖动
- 把字段面板里的类型拖到画布上,新节点放在松开的位置。
- 拖动画布上的节点可以调整顺序,也可以拖进或拖出分组、列表和页面。拖动一个已选中的节点时,所有选中的节点一起移动。
- 拖动时,一条细线标出放下的位置,目标分组带浅色底;靠近画布上下边缘时画布会自动滚动。按 `Esc` 取消。
- 拖动选中节点右边缘的手柄可以调整宽度,按栅格的列吸附,旁边显示当前列数。宽度按表单宽度分别设置时,改的是当前宽度下生效的那一项。
拖动开始时读一次所有节点的位置,移动过程中只做计算,长表单里拖动也不会卡顿。
标签页和分步里的页签暂时不能拖动排序,可以选中页签后用 `⌘` / `Ctrl` + `↑` `↓` 调整顺序。
## 手机上
- 在画布上单指滑动是滚动;按住节点约 0.3 秒后才开始拖动。
- 字段面板和属性面板都是从底部拉出的抽屉,可以往上拉到更高。单击字段面板里的类型就能添加,不需要拖动;单击画布上的节点会打开它的属性。
- 工具栏的“多选”按钮打开后,单击节点会加选或取消选中,不再打开属性,选好后可以一起拖动、复制或放进分组。
设计器宽度不到 560px 时使用这种布局,不到 860px 时字段面板收进工具栏的“字段”按钮。
## 键盘
焦点在画布或结构树上时可以用键盘完成大部分操作。画布和结构树都是读屏可以识别的树形结构,添加、删除、移动、撤销后会读出结果。
| 按键 | 作用 |
| ------------------------------------------ | -------------------------------------------------- |
| `↑` `↓` | 选中上一个、下一个节点 |
| `Shift` + `↑` `↓` | 扩大或缩小选中范围 |
| `→` `←` | 进入第一个子节点、回到上一级;结构树里先展开、收起 |
| `Home` `End` | 选中第一个、最后一个节点 |
| `⌘` / `Ctrl` + `↑` `↓` | 上移、下移选中的节点 |
| `⌘` / `Ctrl` + `D` | 复制 |
| `⌘` / `Ctrl` + `G` | 放进一个新分组 |
| `Delete` `Backspace` | 删除 |
| `⌘` / `Ctrl` + `Z` | 撤销 |
| `⌘` / `Ctrl` + `Shift` + `Z`,`Ctrl` + `Y` | 重做 |
| `Enter` | 跳到属性面板的第一项 |
| `Esc` | 选中上一级 |
| `Space` | 拿起选中的节点,再用方向键选择位置,`Enter` 放下 |
| `Shift` + `F10`,菜单键 | 在画布上打开选中节点的菜单,也可以右键打开 |
连续修改同一项设置(比如一个字一个字地输入标签)在一秒内会合并成一步撤销。
## 预览
工具栏右侧的“预览”切换到填写视图:表单按真实的样子渲染,可以填写、看到联动和校验,提交通过后在下方列出会提交的值。上方可以选择桌面、平板(768px)和手机(375px)的宽度,栅格按表单宽度变化,所以能直接看到每个断点下的排版。手机上预览始终占满屏幕宽度。
`v-model:mode` 绑定当前是设计(`design`)还是预览(`preview`),也可以从页面自己的按钮切换。预览用到选项来源时,把同一份 `sources` 传给设计器。
## 只读
`readonly` 让设计器只用来查看一张表单的结构,比如给没有编辑权限的人看,或者展示历史版本:可以选中节点、在属性面板里查看设置、打开结构树、预览和查看 JSON,但不能添加、拖动、删除、撤销,属性面板里的设置只能查看、选中和复制,左侧面板只有结构树。
只读时 `add`、`remove`、`moveTo`、`replace`、`undo` 这些修改表单的方法什么都不做,`readonly` 属性可以从实例或 `useFormBuilder()` 读到。直接交给 `dispatch` 的事务仍然生效,比如[协同编辑](./collaboration)时其他人的修改。扩展加的按钮、菜单项、快捷键和属性面板里的部分(`inspector`)不会被自动禁用,修改表单的要自己判断 `useFormBuilder().readonly`。`expressionInput` 换上的输入框会收到 `readonly`,只读时应当只能查看。
## 文字
设计器自己的文字(字段类型的名称、按钮、提示、读屏播报)跟随当前语言,内置简体中文、繁体中文和英文。`messages` 可以替换其中一部分,按分组合并:
```vue
```
## API
### FormBuilder Props
| 名称 | 说明 | 类型 | 默认值 |
| ------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ---------- |
| `v-model` | 表单描述,每次修改得到一份新的对象,见[表单描述](./document) | `FormDocument` | — |
| `v-model:selection` | 选中的节点 id,最后一个是最后选中的 | `string[]` | — |
| `v-model:mode` | 设计(`design`)还是预览(`preview`),见[预览](#预览) | `'design' \| 'preview'` | `'design'` |
| `fields` | 内置之外的字段类型,和交给渲染器的是同一份,见[字段类型](./fields) | `FormFieldType[]` | — |
| `functions` | 表达式能调用的函数,和渲染器的一样:预览会执行它们,属性面板补全和检查它们的名字 | `Record` | — |
| `sources` | 选项来源,和渲染器的一样,预览时用 | `Record` | — |
| `validators` | 校验函数,和渲染器的一样:规则里可以选这些名字,预览时会执行 | `Record` | — |
| `readonly` | 只能查看,不能修改,见[只读](#只读) | `boolean` | `false` |
| `bordered` | 外框和圆角;关闭后去掉外框和圆角,用于放进已有边框的容器,见[去掉外框](/guide/theming#去掉外框与调整内边距) | `boolean` | `true` |
| `extensions` | 扩展:字段类型、快捷键、按钮、菜单项和属性面板,见[扩展](./builder-extensions) | `(FormBuilderExtension \| FormBuilderExtension[])[]` | — |
| `messages` | 覆盖设计器的文案,按分组合并,见[文字](#文字) | `FormBuilderMessagesOverride` | — |
### CSS 变量
| 名称 | 说明 | 默认值 |
| --------------------------- | -------- | ------------------------- |
| `--dou-form-builder-border` | 外框颜色 | `var(--dou-color-border)` |
### FormBuilder Events
| 名称 | 说明 | 参数 |
| -------- | -------------------------------------------------------------------------- | ------------------------------ |
| `change` | 每次修改后触发,包括撤销和重做,参数是这次的事务,`steps` 是它做了哪些修改 | `(tr: FormBuilderTransaction)` |
### FormBuilder Slots
| 名称 | 说明 |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `default` | 替换整个布局,自己摆放 `DouFormBuilderPalette`、`DouFormBuilderCanvas`、`DouFormBuilderInspector`、`DouFormBuilderOutline`、`DouFormBuilderPreview` |
| `toolbar` | 默认布局里撤销、重做按钮后面的按钮 |
组件实例上的属性和方法见[用代码修改](./builder-api#api)。