Form 表单

表单是 amis 中核心组件之一，主要作用是提交或者展示表单数据。

基本用法

最基本的用法是配置 表单项 和 提交接口api。

如下我们配置姓名和邮箱表单项，并可以填写数据并提交给接口/api/mock2/form/saveForm。

```schema: scope=”body” { “type”: “form”, “api”: “/api/mock2/form/saveForm”, “body”: [ { “type”: “input-text”, “name”: “name”, “label”: “姓名：” }, { “name”: “email”, “type”: “input-email”, “label”: “邮箱：” } ] }

  2. ## 表单展示
  4. ### 默认模式
  6. 默认展示模式为文字表单项分行显示
  8. ```schema: scope="body"
  9. {
  10.     "type": "form",
  11.     "api": "/api/mock2/form/saveForm",
  12.     "body": [
  13.       {
  14.         "type": "input-text",
  15.         "name": "name",
  16.         "label": "姓名："
  17.       },
  18.       {
  19.         "name": "email",
  20.         "type": "input-email",
  21.         "label": "邮箱："
  22.       }
  23.     ]
  24. }

水平模式

水平模式，左右摆放，左右比率分配。

```schema: scope=”body” { “type”: “form”, “title”: “水平模式”, “mode”: “horizontal”, “body”: [ { “type”: “input-email”, “name”: “email”, “label”: “邮箱”, “required”: true }, { “type”: “input-password”, “name”: “password”, “label”: “密码” }, { “type”: “checkbox”, “name”: “rememberMe”, “label”: “记住登录” } ] }

  2. 可以配置`horizontal`属性，调整偏移量，格式如下：

“horizontal”: { “left”: 2, “right”: 10, “offset”: 2 }

  2. ```schema: scope="body"
  3. {
  4.     "type": "form",
  5.     "title": "水平模式",
  6.     "mode": "horizontal",
  7.     "horizontal": {
  8.       "left": 2,
  9.       "right": 10,
  10.       "offset": 2
  11.     },
  12.     "body": [
  13.       {
  14.         "type": "input-email",
  15.         "name": "email",
  16.         "label": "邮箱",
  17.         "required": true
  18.       },
  19.       {
  20.         "type": "input-password",
  21.         "name": "password",
  22.         "label": "密码"
  23.       },
  24.       {
  25.         "type": "checkbox",
  26.         "name": "rememberMe",
  27.         "label": "记住登录"
  28.       }
  29.     ]
  30. }

通过上面的配置可以看出来水平布局其实按比率分配的。实际上有时候固定左侧宽度更好看点。

  1. "horizontal": {
  2.     "leftFixed": true
  3. }

也可以直接配置 ‘xs’ | ‘sm’ | ‘md’ | ‘lg’ 来定义左侧 label 的宽度。

```schema: scope=”body” { “type”: “form”, “title”: “水平模式”, “mode”: “horizontal”, “horizontal”: { “leftFixed”: “sm” }, “body”: [ { “type”: “input-email”, “name”: “email”, “label”: “邮箱”, “required”: true }, { “type”: “input-password”, “name”: “password”, “label”: “密码” }, { “type”: “checkbox”, “name”: “rememberMe”, “label”: “记住登录” } ] }

  2. #### 两端对齐
  4. 有时表单内容需要两端对齐，可在 horizontal 中增加 justify 配置，注意只对内联控件生效
  6. ```schema: scope="body"
  7. {
  8.   "type": "container",
  9.   "style": {
  10.     "width": "300px",
  11.   },
  12.   "body": [
  13.     {
  14.       "type": "form",
  15.       "title": "两端对齐",
  16.       "mode": "horizontal",
  17.       "horizontal": {
  18.         "justify": true,
  19.         "left": 3,
  20.         "right": 9
  21.       },
  22.       "body": [
  23.         {
  24.           "type": "input-text",
  25.           "name": "name",
  26.           "label": "姓名",
  27.           "required": true
  28.         },
  29.         {
  30.           "type": "input-text",
  31.           "name": "name",
  32.           "label": "班级",
  33.           "required": true
  34.         },
  35.         {
  36.           "type": "switch",
  37.           "name": "status",
  38.           "inputClassName": "is-inline",
  39.           "label": "是否在职",
  40.           "onText": "在职",
  41.           "offText": "非在职"
  42.         }
  43.       ]
  44.     }
  45.   ]
  46. }

label 对齐模式

水平模式下 labelAlign 可以设置标签文本的对齐方式，支持right和left，默认为right。该属性的优先级：表单项 > 表单。

```schema: scope=”body” { “type”: “form”, “title”: “label对齐模式”, “mode”: “horizontal”, “labelAlign”: “left”, “body”: [ { “type”: “input-email”, “name”: “email”, “label”: “邮箱”, “labelAlign”: “right”, “required”: true }, { “type”: “input-password”, “name”: “password”, “label”: “密码”, “required”: true } ] }

  2. ### 内联模式
  4. 使用内联模式展现表单项
  6. ```schema: scope="body"
  7.  {
  8.     "type": "form",
  9.     "title": "内联模式",
  10.     "mode": "inline",
  11.     "body": [
  12.       {
  13.         "type": "input-email",
  14.         "name": "email",
  15.         "label": "邮箱"
  16.       },
  17.       {
  18.         "type": "input-password",
  19.         "name": "password"
  20.       },
  21.       {
  22.         "type": "checkbox",
  23.         "name": "rememberMe",
  24.         "label": "记住登录"
  25.       },
  26.       {
  27.         "type": "submit",
  28.         "label": "登录"
  29.       }
  30.     ]
  31.   }

自定义 label 宽度

水平模式下 labelWidth 可以设置标签文本的自定义宽度，默认单位为px。该属性的优先级：表单项 > 表单。

```schema: scope=”body” { “type”: “form”, “title”: “label对齐模式”, “mode”: “horizontal”, “labelWidth”: 120, “body”: [ { “type”: “input-email”, “name”: “email”, “label”: “邮箱”, “labelWidth”: 200, “required”: true }, { “type”: “input-password”, “name”: “password”, “label”: “密码”, “required”: true }, { “type”: “input-text”, “name”: “address”, “label”: “地址”, “mode”: “inline” }, { “type”: “input-text”, “name”: “mailCode”, “label”: “邮编”, “mode”: “inline”, “labelWidth”: 80 }, { “type”: “radios”, “name”: “mailCode”, “label”: “性别”, “mode”: “row”, “options”: [ { “label”: “Male”, “value”: “male” }, { “label”: “Female”, “value”: “female” } ] } ] }

  2. ### 实现一行展示多个表单项
  4. 有两种方法，一个是通过 `columnCount` 来控制表单显示几列
  6. ```schema: scope="body"
  7.  {
  8.     "type": "form",
  9.     "title": "内联模式",
  10.     "columnCount": 2,
  11.     "body": [
  12.       {
  13.         "type": "input-email",
  14.         "name": "email",
  15.         "label": "邮箱",
  16.         "required": true
  17.       },
  18.       {
  19.         "type": "input-password",
  20.         "name": "password",
  21.         "label": "密码"
  22.       }
  23.     ]
  24.   }

另一个方法是使用 group，它能实现每行显示不同列数，以及不同列的宽度分配情况，可以实现更灵活的控制

```schema: scope=”body” [ { “type”: “form”, “title”: “常规模式”, “body”: [ { “type”: “group”, “body”: [ { “type”: “input-text”, “name”: “text1”, “label”: “文本1” }, { “type”: “input-text”, “name”: “text2”, “label”: “文本2” } ] }, { “type”: “divider” }, { “type”: “group”, “body”: [ { “type”: “input-text”, “name”: “text3”, “label”: “文本3”, “columnRatio”: 4 }, { “type”: “input-text”, “name”: “text4”, “label”: “文本4”, “columnRatio”: 6 }, { “type”: “input-text”, “name”: “text5”, “label”: “文本5” } ] } ] }, { “type”: “form”, “title”: “水平模式”, “mode”: “horizontal”, “body”: [ { “type”: “group”, “body”: [ { “type”: “input-email”, “name”: “email2”, “label”: “邮箱” }, { “type”: “input-password”, “name”: “password2”, “label”: “密码” } ] } ] }, { “type”: “form”, “title”: “内联模式”, “mode”: “inline”, “body”: [ { “type”: “group”, “body”: [ { “type”: “input-email”, “name”: “email”, “label”: “邮箱” }, { “type”: “input-password”, “name”: “password”, “label”: “密码” } ] } ] } ]

  2. ### 底部按钮栏
  4. #### 隐藏默认提交按钮
  6. Form 默认会在底部渲染一个提交按钮，用于执行表单的提交行为。你可以通过两种方式去掉这个默认的提交按钮：
  8. 1. 配置：`"submitText": ""`
  9. 2. 配置：`"actions": []`
  11. ```schema: scope="body"
  12. [
  13.     {
  14.       "type": "form",
  15.       "title": "通过 submitText 去掉提交按钮",
  16.       "submitText": "",
  17.       "body": [
  18.         {
  19.           "type": "input-text",
  20.           "name": "email",
  21.           "label": "邮箱"
  22.         }
  23.       ]
  24.     },
  25.     {
  26.       "type": "form",
  27.       "title": "通过 actions 去掉提交按钮",
  28.       "actions": [],
  29.       "body": [
  30.         {
  31.           "type": "input-text",
  32.           "name": "email",
  33.           "label": "邮箱"
  34.         }
  35.       ]
  36.     }
  37.   ]

配置若干自定义按钮

同样，你可以通过 actions 属性，配置任意你想要的行为按钮。

```schema: scope=”body” { “type”: “form”, “title”: “表单”, “body”: [ { “type”: “input-text”, “name”: “email”, “label”: “邮箱” }, { “type”: “input-password”, “name”: “password”, “label”: “密码” } ], “actions”: [ { “type”: “submit”, “label”: “登录” }, { “type”: “action”, “actionType”: “dialog”, “label”: “登录须知”, “dialog”: { “title”: “登录须知”, “body”: “登录须知” } }, { “type”: “button”, “label”: “百度一下”, “url”: “https://www.baidu.com/“ } ] }

  2. 请记住，如果想触发表单提交行为，请配置`"actionType": "submit"`或`"type": "submit"`按钮
  4. ### 去掉表单边框
  6. 通过配置`"wrapWithPanel": false`，可以去掉默认表单边框（包括标题，按钮栏以及边距样式等）。
  8. ```schema: scope="body"
  9. {
  10.     "type": "form",
  11.     "wrapWithPanel": false,
  12.     "body": [
  13.       {
  14.         "type": "input-text",
  15.         "name": "email",
  16.         "label": "邮箱"
  17.       },
  18.       {
  19.         "type": "input-password",
  20.         "name": "password",
  21.         "label": "密码"
  22.       }
  23.     ]
  24.   }

注意！配置该属性后，title和actions属性将失效并无法渲染，请在表单内自行配置。

固定底部栏

如果表单项较多导致表单过长，而不方便操作底部的按钮栏，可以配置"affixFooter": true属性，将底部按钮栏固定在浏览器底部

表单项数据初始化

表单可以通过配置initApi，实现表单初始化时请求接口，用于展示数据或初始化表单项。

```schema: scope=”body” { “type”: “form”, “initApi”: “/api/mock2/form/initData”, “title”: “编辑用户信息”, “body”: [ { “type”: “input-text”, “name”: “name”, “label”: “姓名” }, { “type”: “input-text”, “name”: “email”, “label”: “邮箱” } ] }

  2. 比如以上这个例子接口返回为

{ status: 0, msg: “”, data: { name: “Amis Renderer”, author: “fex”, date: 1615978757, info: “” } }

  2. 第一个表单项的 name 配置为 `name`，所以这个表单初始化完毕后展示 `Amis Renderer`。
  4. > 表单项的 value 是不支持表达式，所以不要尝试用 `value: "${xxx}"` 来关联数据。
  6. ### 轮询初始化请求
  8. Form 支持轮询初始化接口，步骤如下：
  10. 1. 配置`initApi`
  11. 2. 配置 `interval`：单位为毫秒，最小 `1000`
  13. ```schema: scope="body"
  14. {
  15.     "type": "form",
  16.     "initApi": "/api/mock2/page/initData",
  17.     "interval": 3000,
  18.     "title": "表单",
  19.     "body": [
  20.       {
  21.         "type": "input-text",
  22.         "name": "date",
  23.         "label": "时间戳"
  24.       }
  25.     ]
  26.   }

如果希望在满足某个条件的情况下停止轮询，配置stopAutoRefreshWhen表达式。

```schema: scope=”body” { “type”: “form”, “initApi”: “/api/mock2/page/initData”, “interval”: 3000, “title”: “表单”, “stopAutoRefreshWhen”: “this.date % 5”, “body”: [ { “type”: “input-text”, “name”: “date”, “label”: “时间戳” } ] }

  2. ### 静态初始化数据域
  4. 我们也可以手动设置 form 的数据域来初始化多个表单项值
  6. ```schema: scope="body"
  7. {
  8.     "type": "form",
  9.     "data": {
  10.       "name": "rick",
  11.       "email": "rick@gmail.com"
  12.     },
  13.     "title": "用户信息",
  14.     "body": [
  15.       {
  16.         "type": "input-text",
  17.         "name": "name",
  18.         "label": "姓名"
  19.       },
  20.       {
  21.         "type": "input-email",
  22.         "name": "email",
  23.         "label": "邮箱"
  24.       }
  25.     ]
  26.   }

注意这里的 data 会进行数据映射，如果想不映射，需要进行转义，比如下面的例子

```schema: scope=”body” { “type”: “form”, “data”: { “name”: “\${rick}”, “email”: “rick@gmail.com” }, “title”: “用户信息”, “body”: [ { “type”: “input-text”, “name”: “name”, “label”: “姓名” }, { “type”: “input-email”, “name”: “email”, “label”: “邮箱” } ] }

  2. ### 数据格式一致性问题
  4. 当表单来初始化表单项值时，需要保持数据格式的一致性。
  6. 如果表单初始化的值与表单项配置的数据格式不符合，而且用户没有再次操作该表单项，而直接提交表单，那么会将当前默认值原封不动的提交给后端，也许会导致不一致性的问题，我们看一个例子：
  8. ```schema: scope="body"
  9. {
  10.     "type": "form",
  11.     "data": {
  12.         "select": ["a", "c"]
  13.     },
  14.     "body": [
  15.         {
  16.             "label": "选项",
  17.             "type": "select",
  18.             "name": "select",
  19.             "multiple": true,
  20.             "options": [
  21.                 {
  22.                     "label":"A",
  23.                     "value":"a"
  24.                 },
  25.                 {
  26.                     "label":"B",
  27.                     "value":"b"
  28.                 },
  29.                 {
  30.                     "label":"C",
  31.                     "value":"c"
  32.                 }
  33.             ]
  34.         }
  35.     ]
  36. }

上例中， select 我们配置了"multiple": true，预期中，我们希望选中 A 和 C 项时，表单项的数据格式为："a,c"，但是我们表单数据域中，select默认值为"value": ["a", "c"]，并不符合我们当前表单项的数据格式配置，这样会导致两个问题：

  1. 有可能不会默认选中 A 和 C 选项；
  2. 当不操作该表单项，直接提交时，预期是："a,c"，但提交给后端的数据为：["a", "c"]，导致了不一致性的问题。

通过 initApi 配置默认值同理，不再赘述

因此一定确保默认值与选择器表单项数据格式配置相匹配。

表单提交

配置api属性，当表单执行提交行为时，会默认将当前表单数据域中的数据使用post方式发送给所配置api

```schema: scope=”body” { “type”: “form”, “api”: “/api/saveForm”, “title”: “用户信息”, “body”: [ { “type”: “input-text”, “name”: “name”, “label”: “姓名” }, { “type”: “input-email”, “name”: “email”, “label”: “邮箱” } ] }

  2. 点击提交按钮，会看到发送表单请求，请求数据体为：
  4. ```json
  5. {
  6.   "name": "xxx",
  7.   "email": "xxx@xx.com"
  8. }

发送请求默认为 POST 方式，会将所有表单项整理成一个对象发送过过去。除此之外你可以主动获取以下信息。

  • diff 只会包含 diff 结果
  • prinstine 原始数据 如:
  1. {
  2.   "api": {
  3.     "method": "post",
  4.     "url": "/api/xxx/save",
  5.     "data": {
  6.       "modified": "$$",
  7.       "diff": "${diff}",
  8.       "origin": "${prinstine}"
  9.     }
  10.   }
  11. }

如果 返回了 data 对象，且是对象，会把结果 merge 到表单数据里面。

当你需要配置特定的请求方式，请求体，header时，使用对象类型 api 配置，并使用 数据映射 进行数据配置。

下面示例我们更改了请求方法为PUT，并在原提交数据的基础上添加一个字段"_from"。更多用法查看 API 文档 和 数据映射文档

```schema: scope=”body” { “type”: “form”, “initApi”: { “method”: “put”, “url”: “/api/mock2/page/initData”, “data”: { “&”: “”, “_from”: “browser” } }, “title”: “用户信息”, “body”: [ { “type”: “input-text”, “name”: “name”, “label”: “姓名” }, { “type”: “input-email”, “name”: “email”, “label”: “邮箱” } ] }

  2. 触发表单提交行为有下面几种方式：
  4. 1. 默认的`提交按钮`
  5. 2. 为行为按钮配置`"actionType": "submit"`
  6. 3. 配置`"type": "submit"`的按钮
  8. ### 轮询提交请求
  10. 通过设置`asyncApi`，当表单提交发送保存接口后，还会继续轮询请求该接口，默认间隔为`3秒`，直到返回 `finished` 属性为 `true` 才 结束。
  12. ```schema: scope="body"
  13. {
  14.     "type": "form",
  15.     "initApi": "/api/mock2/page/initData",
  16.     "asyncApi": "/api/mock2/page/initData",
  17.     "title": "用户信息",
  18.     "body": [
  19.       {
  20.         "type": "input-text",
  21.         "name": "name",
  22.         "label": "姓名"
  23.       },
  24.       {
  25.         "type": "input-email",
  26.         "name": "email",
  27.         "label": "邮箱"
  28.       }
  29.     ]
  30.   }

如果决定结束轮询的标识字段名不是 finished，请设置finishedField属性，比如："finishedField": "is_success"

表单校验

一般可以通过在表单项格式校验中，配置校验规则完成校验，但是有时候，我们需要组合多个表单项实现一些校验，这时可以通过配置 rules 来实现组合校验。

例如下例，我们想校验 a 和 b 表单项不可以同时有值，否则就报错，则可以进行如下配置：

  1. {
  2.   "type": "form",
  3.   "api": "/api/form/saveForm",
  4.   "rules": [
  5.     {
  6.       "rule": "!(data.a && data.b)",
  7.       "message": "a 和 b 不能同时有值"
  8.     }
  9.   ],
  10.   "body": [
  11.     {
  12.       "type": "input-text",
  13.       "name": "a",
  14.       "label": "A"
  15.     },
  16.     {
  17.       "type": "input-text",
  18.       "name": "b",
  19.       "label": "B"
  20.     }
  21.   ]
  22. }

rule 编写使用 表达式

组合校验高亮表单项

1.6.5 及以上版本

默认组合校验的错误信息显示在表单的底部，如果希望可以定位到表单项自己，则可以通过配置 name 来高亮错误。

  1. {
  2.   "type": "form",
  3.   "api": "/api/form/saveForm",
  4.   "rules": [
  5.     {
  6.       "rule": "!(data.a && data.b)",
  7.       "message": "a 和 b 不能同时有值",
  8.       "name": ["a", "b"]
  9.     }
  10.   ],
  11.   "body": [
  12.     {
  13.       "type": "input-text",
  14.       "name": "a",
  15.       "label": "A"
  16.     },
  17.     {
  18.       "type": "input-text",
  19.       "name": "b",
  20.       "label": "B"
  21.     }
  22.   ]
  23. }

重置表单

配置"type": "reset"或者"actionType": "reset"的按钮，可以实现点击重置表单项值。

```schema: scope=”body” { “type”: “form”, “body”: [ { “type”: “input-text”, “name”: “name”, “label”: “姓名” }, { “type”: “input-email”, “name”: “email”, “label”: “邮箱” } ], “actions”: [ { “type”: “reset”, “label”: “重置” }, { “type”: “submit”, “label”: “保存” } ] }

  2. > **请注意：**这里的重置是将表单数据域重置到**初始状态**，**而不是清空**，如果你配置了初始化接口，那么重置操作是会**将表单项重置至初始化表单项值**
  4. ## 表单数据域调试
  6. 配置`debug:true`可以查看当前表单的数据域数据详情，方便数据映射、表达式等功能调试，如下，你可以修改表单项查看数据域变化
  8. ```schema: scope="body"
  9. {
  10.     "type": "form",
  11.     "title": "用户信息",
  12.     "debug": true,
  13.     "body": [
  14.       {
  15.         "type": "input-text",
  16.         "name": "name",
  17.         "label": "姓名"
  18.       },
  19.       {
  20.         "type": "input-email",
  21.         "name": "email",
  22.         "label": "邮箱"
  23.       }
  24.     ]
  25.   }

该配置不会展示完整的数据链，只会展示当前表单的数据域

禁用数据链

默认表单是可以获取到完整数据链中的数据的，但是该默认行为不适用于所有场景，例如：

在 CRUD 的列表项中配置弹框，弹框中有一个表单，则该表单项中所有的同name表单项都会根据上层crud的行数据进行初始化，如果你是实现编辑的功能那并没有是什么问题，但是如果你是新建功能，那么这将不符合你的预期，你可以手动设置"canAccessSuperData": false来关闭该行为

提交后行为

表单提交成功后，可以执行一些行为。

重置表单

如果想提交表单成功后，重置当前表单至初始状态，可以配置"resetAfterSubmit": true。

```schema: scope=”body” { “type”: “form”, “api”: “/api/mock2/form/saveForm”, “resetAfterSubmit”: true, “body”: [ { “type”: “input-text”, “name”: “name”, “label”: “姓名：” }, { “name”: “email”, “type”: “input-email”, “label”: “邮箱：” } ] }

  2. 编辑表单项，点击提交，成功后会发现表单项的值会重置到初始状态，即空
  4. > 注意，如果表单项有默认值，则会将该表单项的值重置至该默认值。
  6. ### 跳转页面
  8. 配置`redirect`属性，可以指定表单提交成功后要跳转至的页面
  10. ```schema: scope="body"
  11. {
  12.     "type": "form",
  13.     "initApi": "/api/mock2/page/initData",
  14.     "redirect": "/user/list",
  15.     "title": "用户信息",
  16.     "body": [
  17.       {
  18.         "type": "input-text",
  19.         "name": "name",
  20.         "label": "姓名"
  21.       },
  22.       {
  23.         "type": "input-email",
  24.         "name": "email",
  25.         "label": "邮箱"
  26.       }
  27.     ]
  28.   }

刷新目标组件

配置reload属性为其他组件name值，可以在表单提交成功之后，刷新指定组件。

```schema: scope=”body” [ { “type”: “form”, “initApi”: “/api/mock2/page/initData”, “title”: “用户信息”, “reload”: “my_service”, “body”: [ { “type”: “input-text”, “name”: “name”, “label”: “姓名” }, { “type”: “input-email”, “name”: “email”, “label”: “邮箱” } ] }, { “type”: “service”, “name”: “my_service”, “api”: “/api/mock2/page/initData”, “body”: “service初识数据” } ]

  2. 上例中`form`提交成功后，会触发`name`为`my_service`的`Service`组件重新请求初始化接口
  4. 上面示例是一种[组件间联动]($docs-zh-CN-docs-concepts-linkage#%E7%BB%84%E4%BB%B6%E9%97%B4%E8%81%94%E5%8A%A8)
  6. ### 显示提交的返回结果
  8. 默认情况下表单提交返回结果会写入当前表单的数据域，如果要显示在当前表单，可以直接使用 `static` 类型，比如下面的例子
  10. ```schema: scope="body"
  11. {
  12.   "type": "form",
  13.   "api": "/api/mock2/form/saveForm",
  14.   "title": "用户信息",
  15.   "body": [
  16.     {
  17.       "type": "input-text",
  18.       "name": "name",
  19.       "label": "姓名"
  20.     },
  21.     {
  22.       "type": "static",
  23.       "name": "id",
  24.       "visibleOn": "typeof data.id !== 'undefined'",
  25.       "label": "返回 ID"
  26.     }
  27.   ]
  28. }

将提交返回内容发送到其它组件

还可以将返回结果发送到其它组件，首先设置另一个表单的 name，然后通过 reload 配置参数来提交

```schema: scope=”body” [ { “type”: “form”, “api”: “/api/mock2/form/saveForm”, “title”: “用户信息”, “reload”: “otherForm?id=${id}”, “body”: [ { “type”: “input-text”, “name”: “name”, “label”: “姓名” } ] }, { “type”: “form”, “name”: “otherForm”, “title”: “返回结果”, “actions”: [], “body”: [ { “type”: “static”, “name”: “id”, “label”: “返回 ID” } ] } ]

  2. ### 将数据域发送给目标组件
  4. 配置`target`属性为目标组件`name`值，可以在触发提交行为后，将当前表单的数据域发送给目标组件。
  6. ```schema: scope="body"
  7. [
  8.     {
  9.       "type": "form",
  10.       "target": "detailForm",
  11.       "body": [
  12.         {
  13.           "type": "input-text",
  14.           "placeholder": "关键字",
  15.           "name": "keywords"
  16.         }
  17.       ]
  18.     },
  19.     {
  20.       "type": "form",
  21.       "name": "detailForm",
  22.       "initApi": "/api/mock2/page/initData?keywords=${keywords}",
  23.       "body": [
  24.         {
  25.           "label": "名称",
  26.           "type": "static",
  27.           "name": "name"
  28.         },
  29.         {
  30.           "label": "作者",
  31.           "type": "static",
  32.           "name": "author"
  33.         },
  34.         {
  35.           "label": "关键字",
  36.           "type": "static",
  37.           "name": "keywords"
  38.         },
  39.         {
  40.           "label": "请求时间",
  41.           "type": "static-datetime",
  42.           "format": "YYYY-MM-DD HH:mm:ss",
  43.           "name": "date"
  44.         }
  45.       ]
  46.     }
  47.   ]

第一个表单在提交时，会将它的表单数据域数据发送给detailForm表单，触发detailForm的初始化接口联动，重新请求接口更新数据域，并更新关键字表单项。

上面示例组合使用了 组件间联动 和 接口联动

持久化保存表单项数据

表单默认在重置之后（切换页面、弹框中表单关闭表单），会自动清空掉表单中的所有数据，如果你想持久化保留当前表单项的数据而不清空它，那么通过 Form 配置 persistData: "xxx"，指定一个 key ，来实现数据持久化保存

注意，如果使用在 CRUD 列表中的编辑框内的 Form 中，可以利用数据映射语法，persistData: "xxx:${id}"，来为 form 指定一个唯一的 key

如果想提交成功后，清空该缓存，则配置"clearPersistDataAfterSubmit": true

禁用回车提交

表单默认情况下回车就会提交，如果想阻止这个行为，可以加上 preventEnterSubmit 配置项。

schema: scope="body" { "type": "form", "api": "/api/mock2/form/saveForm", "preventEnterSubmit": true, "body": [ { "type": "input-text", "name": "name", "label": "姓名：" }, { "name": "email", "type": "input-email", "label": "邮箱：" } ] }

属性表

属性名 类型 默认值 说明
type string "form" 指定为 Form 渲染器
name string 设置一个名字后，方便其他组件与其通信
mode string normal 表单展示方式，可以是：normal、horizontal 或者 inline
horizontal Object {"left":"col-sm-2", "right":"col-sm-10", "offset":"col-sm-offset-2"} 当 mode 为 horizontal 时有用，用来控制 label
labelAlign `”right” \ “left”` "right" 表单项标签对齐方式，默认右对齐，仅在 mode为horizontal 时生效
labelWidth `number \ string` 表单项标签自定义宽度
title string "表单" Form 的标题
submitText String "提交" 默认的提交按钮名称，如果设置成空，则可以把默认按钮去掉。
className string 外层 Dom 的类名
body Array<表单项 or SchemaNode > Form 表单项集合
actions Array<行为按钮> Form 提交按钮，成员为 Action
messages Object 消息提示覆写，默认消息读取的是 API 返回的消息，但是在此可以覆写它。
messages.fetchSuccess string 获取成功时提示
messages.fetchFailed string 获取失败时提示
messages.saveSuccess string 保存成功时提示
messages.saveFailed string 保存失败时提示
wrapWithPanel boolean true 是否让 Form 用 panel 包起来，设置为 false 后，actions 将无效。
panelClassName string 外层 panel 的类名
api API Form 用来保存数据的 api。
initApi API Form 用来获取初始数据的 api。
rules Array<{rule:string;message:string;name?: string[]}> 表单组合校验规则
interval number 3000 刷新时间(最低 3000)
silentPolling boolean false 配置刷新时是否显示加载动画
stopAutoRefreshWhen string "" 通过表达式 来配置停止刷新的条件
initAsyncApi API Form 用来获取初始数据的 api,与 initApi 不同的是，会一直轮询请求该接口，直到返回 finished 属性为 true 才 结束。
initFetch boolean true 设置了 initApi 或者 initAsyncApi 后，默认会开始就发请求，设置为 false 后就不会起始就请求接口
initFetchOn string 用表达式来配置
initFinishedField string finished 设置了 initAsyncApi 后，默认会从返回数据的 data.finished 来判断是否完成，也可以设置成其他的 xxx，就会从 data.xxx 中获取
initCheckInterval number 3000 设置了 initAsyncApi 以后，默认拉取的时间间隔
asyncApi API 设置此属性后，表单提交发送保存接口后，还会继续轮询请求该接口，直到返回 finished 属性为 true 才 结束。
checkInterval number 3000 轮询请求的时间间隔，默认为 3 秒。设置 asyncApi 才有效
finishedField string "finished" 如果决定结束的字段名不是 finished 请设置此属性，比如 is_success
submitOnChange boolean false 表单修改即提交
submitOnInit boolean false 初始就提交一次
resetAfterSubmit boolean false 提交后是否重置表单
primaryField string "id" 设置主键 id, 当设置后，检测表单是否完成时（asyncApi），只会携带此数据。
target string 默认表单提交自己会通过发送 api 保存数据，但是也可以设定另外一个 form 的 name 值，或者另外一个 CRUD 模型的 name 值。 如果 target 目标是一个 Form ，则目标 Form 会重新触发 initApi，api 可以拿到当前 form 数据。如果目标是一个 CRUD 模型，则目标模型会重新触发搜索，参数为当前 Form 数据。当目标是 window 时，会把当前表单的数据附带到页面地址上。
redirect string 设置此属性后，Form 保存成功后，自动跳转到指定页面。支持相对地址，和绝对地址（相对于组内的）。
reload string 操作完后刷新目标对象。请填写目标组件设置的 name 值，如果填写为 window 则让当前页面整体刷新。
autoFocus boolean false 是否自动聚焦。
canAccessSuperData boolean true 指定是否可以自动获取上层的数据并映射到表单项上
persistData string "" 指定一个唯一的 key，来配置当前表单是否开启本地缓存
clearPersistDataAfterSubmit boolean true 指定表单提交成功后是否清除本地缓存
preventEnterSubmit boolean false 禁用回车提交表单
trimValues boolean false trim 当前表单项的每一个值
promptPageLeave boolean false form 还没保存，即将离开页面前是否弹框确认。
columnCount number 0 表单项显示为几列
inheritData booelan true 默认表单是采用数据链的形式创建个自己的数据域，表单提交的时候只会发送自己这个数据域的数据，如果希望共用上层数据域可以设置这个属性为 false，这样上层数据域的数据不需要在表单中用隐藏域或者显式映射才能发送了。

事件表

当前组件会对外派发以下事件，可以通过onEvent来监听这些事件，并通过actions来配置执行的动作，在actions中可以通过event.data.xxx事件参数变量来获取事件产生的数据，详细请查看事件动作。

事件名称 事件参数 说明
inited event.data: object initApi 远程请求返回的初始化数据 远程初始化接口请求成功时触发
change event.data: object 当前表单数据 表单值变化时触发
formItemValidateSucc event.data: object 当前表单数据 表单项校验成功时触发
formItemValidateError event.data: object 当前表单数据 表单项校验失败时触发
validateSucc event.data: object 当前表单数据 表单校验成功时触发
validateError event.data: object 当前表单数据 表单校验成功时触发
submitSucc event.data.result: object api 远程请求成功后返回的结果数据 提交成功时触发
submitFail event.data.error: object api 远程请求失败后返回的错误信息 提交失败时触发

动作表

当前组件对外暴露以下特性动作，其他组件可以通过指定actionType: 动作名称、componentId: 该组件id来触发这些动作，动作配置可以通过args: {动作配置项名称: xxx}来配置具体的参数，详细请查看事件动作。

动作名称 动作配置 说明
submit - 提交表单
reset - 重置表单
clear - 清空表单
validate - 校验表单
reload - 刷新（重新加载）
setValue value: object 更新的表单数据 更新数据，对数据进行 merge