# Form 表单
# install
tnpm i -S @sula/form
# usage
import Form from "@sula/form";
# API
# layout
- 类型:
'vertical' | 'horizontal' | 'inline'
- 默认值:
'horizontal'
表单布局配置,vertical
👉 垂直布局,horizontal
👉 水平布局,inline
👉 行内布局
# itemLayout
- 类型:
object
- 默认值:
{ span: 24, labelCol: { span: 6 }, wrapperCol: { span: 16 } }
表单项布局分布,它内部可配置属性如下:
属性名 | 说明 | 类型 | 默认值 |
---|---|---|---|
gutter | 栅格间隔,作用在表单项所在行 Row 上,同Antd/Grid 栅格/Row/gutter | number | 0 |
span | 栅格占位格数,作用在表单项行内部上,同Antd/Grid 栅格/Col/span | number | 24 |
offset | 栅格左侧的间隔格数,作用在表单项行内部上,同Antd/Grid 栅格/Col/offset | number | 0 |
labelCol | 表单项 label 标签布局,可设置 span、offset,方式同上 👆,同Antd/Form/labelCol | object | { span: 6 } |
wrapperCol | 表单项内部表单控件布局,方式同 labelCol👆 | object | { span: 16 } |
使用 tips:
- 属性支持顶层统一配置,也支持在为表单项单独配置,优先级高于顶层
- itemLayout 的作用和默认值随 layout 的值不同有所差异,具体差异如下
layout === 'vertical'
不支持配置 labelCol
默认值:
{ span: 24; offset: 0; gutter: 24; }
layout === 'horizontal'
- 默认值:
{
span: 24;
offset: 0;
gutter: 24;
labelCol: {
span: 8,
};
wrapperCol: {
span: 12,
}
}
layout === 'inline'
- 此时不为表单项添加布局组件包裹,属性配置全部无效,用户可通过 style 进行定制
# mode
- 类型:
'create' | 'view' | 'edit'
- 默认值:
'create'
表单模式,create
👉 创建模式,view
👉 查看模式,edit
👉 编辑模式
# container
- 类型:
ReactElement | (
ctx) => ReactElement |
RenderType - 默认值:
<div />
表单容器,容器组件会包裹表单
示例:
// 基本写法
container: <div style={{ border: '1px solid #000' }}/>
// 配置化方法写法
container: (ctx) => {
return <Card title={ctx.layout} />;
}
// 配置化属性写法:
container: {
type: 'card',
props: {
title: 'Title',
}
}
# dependency
- 类型:
object
- 默认值:
-
表单组关联关系,仅支持 visible 关联,详细请查看dependency
示例:
{
container: {
type: 'div',
props: {
style: {
padding: 4,
border: '1px solid tomato',
}
},
},
initialVisible: false,
dependency: {
visible: {
relates: ['type'],
inputs: [
['content']
],
output: true,
defaultOutput: false,
}
},
fields: [{
name: 'contentInput',
render: 'input',
label: '内容输入框',
}]
}
# fields
- 类型:
Array<
Field>
- 默认值:
-
表单控件配置
示例:
fields: [
{
name: "sula",
label: "Sula",
render: "input"
}
];
# initialValues
- 类型:
object
- 默认值:
-
表单初始值
注意
- 仅在初始设置时生效,不会随设置值的改变而变化
- 可以通过实例方法改变表单值
- 不支持在单项设置表单初始值,请在 initialValues 中进行配置
# remoteValues
- 类型: FetchType
- 默认值:
-
表单初始值远程请求配置
示例:
remoteValues: {
url: '表单初始值数据请求地址',
method: '请求方法',
params: {
// 请求参数
},
converter: (ctx, config) => {
//请求返回数据转化 可通过ctx.data获取接口返回数据
},
}
# plugins
- 类型:
Array<
Plugin>
- 默认值:
-
业务插件
# onCascade
- 类型:
([{name, value}]) => void
- 默认值:
-
级联项值发生变化时的回调函数。
参数 | 说明 | 类型 |
---|---|---|
name | 触发级联项表单项的数组 name | string[] |
value | 触发级联表单项的值 | any |
# state
- 类型:
object
- 默认值:
-
表单状态,可关联外部 state,当 state 改变时,表单内部视图会更新
tips
- 可以在配置方法中,通过配置方法参数ctx.state 拿到 state 属性
示例:
<Form
state={{
name: this.state.name
}}
fields={[
{
name: "input",
label: "input",
render: ctx => {
return <Input placeholder={ctx.state.name} />;
}
}
]}
/>
# 其他
更多配置请参考Form
# 实例方法
注意
- 可以通过 ref 属性获取实例方法
- form 内所有配置属性,均支持配置成方法,ctx 为配置方法的第一个入参,通过 ctx.form 可获取到 form 实例提供的方法
- setFields()
- setFieldSource()
- setFieldDisabled()
- setFieldsValue()
- setFieldValue()
- setFieldVisible()
- validateGroupFields()
- validateFields()
- getFieldValue()
- getFieldsValue()
- resetFields()
- submit()
更多实例方法,可查看useForm
# setFields(store)
setFields([
{
name: "input",
value: "sula",
touched: true,
validating: false,
errors: ["Sula is required"]
}
]);
设置表单的 value、touched、validating、errors 属性,会根据dependency设置触发级联
# setFieldSource(name, source)
setFieldSource("checkboxgroup", [
{ text: "Sula", value: "sula" },
{ text: "AntD", value: "antd" }
]);
设置某一表单项的数据源。
# setFieldDisabled(name, disabled)
setFieldDisabled("input", true);
设置某一表单项的 disabled 状态
# setFieldsValue(store)
setFieldsValue({
input: "sula",
checkboxgroup: "antd"
});
设置表单值,会根据dependency设置触发级联
注意
对于值关联,如果a可以影响b,如果setFieldsValue({a: 1, b:2}),那么a将不会关联影响b的值;如果setFieldsValue({a: 1}),则会关联影响b的值
# setFieldValue(name, value)
setFieldValue("input", "sula");
设置某一表单项的值,会根据dependency设置触发级联
# setFieldVisible(name, visible)
setFieldVisible("input", false);
设置某一表单项的 visible 状态
# validateGroupFields(groupName)
按组验证表单,返回 Promise 函数
// sula代表了groupName
validateGroupFields("sula").then(data => {
// 校验通过
fetch({
url: '/api/info',
method: 'POST',
params: data,
})
}, (error) => {
// 校验不通过
});
tips
可以嵌套收集该组下所有field的值
# validateFields(nameList?)
validateFields().then(data => {
// 校验通过,发起请求或者其他操作
fetch({
url: '/api/info',
method: 'POST',
params: data,
})
}, (error) => {
// 校验不通过
});
验证表单,如果输入参数 nameList,则验证 nameList 表单,返回 Promise 函数
# getFieldValue(name)
getFieldValue("sula");
获取某一表单项的值
# getFieldsValue(nameList)
getFieldsValue();
获取表单值,如果输入参数 nameList,则获取 nameList 项的值
# resetFields(nameList)
resetFields();
重置表单,如果输入参数 nameList,则重置 nameList 表单
# submit()
submit();
提交表单
# ctx
sula 内所有配置属性,均支持配置方法,ctx 为该方法的第一个参数,配置给不同属性时,ctx 内容会有差异
示例:
const fields = [
{
name: "input",
label: "Input",
render: ctx => {
return <Input disabled={ctx.disabled} />;
}
}
];
# 参数及适用范围
render | action | dependency | validator | container | convertParms | converter | |
---|---|---|---|---|---|---|---|
form | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
state | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
disabled | ✅ | ✅ | - | ✅ | ✅ | - | - |
mode | ✅ | ✅ | - | ✅ | ✅ | ✅ | ✅ |
source | ✅ | ✅ | - | ✅ | - | - | - |
value | ✅ | ✅ | - | ✅ | - | - | - |
visible | ✅ | ✅ | - | ✅ | - | - | - |
groupName | ✅ | ✅ | - | ✅ | - | - | - |
label | - | - | - | ✅ | - | - | - |
name | - | - | ✅ | ✅ | - | - | - |
relates | - | - | ✅ | - | - | - | - |
type | - | - | ✅ | - | - | - | - |
getPrevFieldValue() | - | - | ✅ | - | - | - | - |
params | - | - | - | - | - | ✅ | - |
data | - | - | - | - | - | - | ✅ |
# form
- 类型:
object
实例方法,请查看form 实例
# state
- 类型:
object
表单状态,设置在 Form 上的state
# values
- 类型:
object
表单值
# disabled
适用于 render、validator、action。
- 类型:
boolean
是否禁用
# mode
- 类型:
'edit' | 'view' | 'create'
表单模式
# source
适用于 redner、validator、action
- 类型:
object
该表单项的数据源
# value
适用于 render、validator、action、dependency
- 类型:
any
该表单项的值
# visible
适用于 render、validator、action
- 类型:
boolean
是否显示
# groupName
适用于 render、validator、action
- 类型:
string
该表单项所在的组名称
# label
仅适用于 validator
- 类型:
string
该表单项名称
# name
适用于 validator、dependency
- 类型:
string | number | Array<string|number>
该表单项在表单中的 key
# relates
仅适用于 dependency
- 类型:
Array
级联触发的关联项数组
# type
仅适用于 dependency
- 类型:
'visible' | 'value' | 'source' | 'disabled'
级联触发的类型
# getPrevFieldValue()
仅适用于 dependency
- 类型:
(name) => any
获取某表单项级联变化前的值
参数 | 说明 | 类型 | 默认值 |
---|---|---|---|
name | 表单项 name 属性 | string | number | Array<string|number> | - |
# params
仅适用于 convertParms
- 类型:
object
请求参数
# data
仅适用于 converter
- 类型:
object
请求结果
# Field
表单控件项配置,每项配置属性如下:
# name
- 类型:
string | number | Array<string|number>
- 默认值:
-
表单项 name 属性,对应表单中的 key,数组写法适用于多个结构相同的表单组List,类似于sula-ruler。
示例:
"fields": [
{
"container": {
"type": "card",
},
"fields": [
{
"name": [1, 'apple'],
"label": "苹果1",
"render": {
"type": "input",
"props": {
"placeholder": "苹果1"
}
}
}
]
},
{
"container": {
"type": "card",
},
"fields": [
{
"name": [2, 'apple'],
"label": "苹果2",
"render": {
"type": "input",
"props": {
"placeholder": "苹果2"
}
}
}
]
},
{
"container": {
"type": "card",
},
"fields": [
{
"name": [3, 'apple'],
"label": "苹果3",
"render": {
"type": "input",
"props": {
"placeholder": "苹果3"
}
}
}
]
}
]
# label
- 类型:
string
- 默认值:
-
表单项名称
# layout
- 类型:
'vertical' | 'horizontal' | 'inline'
- 默认值:
'horizontal'
表单布局配置,优先级高于顶层配置,同 👆layout
# itemLayout
- 类型:
object
- 默认值:
{ span: 24, labelCol: { span: 6 }, wrapperCol: { span: 16 } }
表单项布局分布,优先级高于顶层配置,同 👆itemLayout
# render
- 类型:
(
ctx) => ReactNode |
RenderType - 默认值:
-
表单项控件
示例:
// 配置化方法写法
render: (ctx) => {
return <Input disabled={ctx.disabled} />
}
// 配置化属性写法
render: {
type: 'input',
props: {
placeholder: 'Please input',
}
}
# viewRender
- 类型:
(
ctx) => ReactNode |
RenderType - 默认值:
-
表单 mode 为 view 模式时,优先 viewRender,未配置则使用 render,写法同render
# editRender
- 类型:
(
ctx) => ReactNode |
RenderType - 默认值:
-
表单 mode 为 edit 模式时,优先 editRender,未配置则使用 render,写法同render
# rules
- 类型:
Array<
Rule>
- 默认值:
-
校验规则
validator 示例:
rules: [
{
validator: ctx => {
if (ctx.value === "ice cream") {
return Promise.reject("Can not be ice cream");
}
return Promise.resolve();
}
},
{
validator: "whitespace"
}
];
# wrapFormItem
- 类型:
boolean
- 默认值:
true
是否使用Form.Item
包裹控件
# initialDisabled
- 类型:
boolean
- 默认值:
false
表单项初始禁用状态
# initialVisible
- 类型:
boolean
- 默认值:
true
表单项初始是否显示
# initialSource
- 类型:
any
- 默认值:
-
表单项初始数据源
# remoteSource
- 类型: FetchType
- 默认值:
-
表单项远程数据源
示例:
remoteSource: {
url: 'api/tasklist.json',
mehtod: 'get',
}
# dependency
- 类型:
object
- 默认值:
-
表单关联关系,可以设置 disabled、source、value、visible 四个属性,详细请查看dependency
示例:
dependency: {
visible: { // 当type字段输入'fruit'或者'vegetables'时,可见 其余不可见
relates: ['type'],
inputs: [['fruit', 'vegetables']],
output: true,
defaultOutput: false,
},
source: { // type字段输入不同字段对应不同数据源
relates: ['type'],
cases: [
{ inputs: [['fruit']], output: fruitSource },
{ inputs: [['vegetables']], output: vegetablesSource },
],
defaultOutput: [],
},
value: { // type变化时 清空值
relates: ['type'],
defaultOutput: '',
}
},
# fields
- 类型:
Array<
Field>
- 默认值:
-
如果字段中有 fields 的话,该项会被处理成一组,name 对应组名称 groupName,groupName 在 一个 sula-form 中名字唯一。
示例:
const groupFields = [
{
name: "group1",
container: {
type: "card",
props: {
title: "group1",
style: {
marginBottom: 16
}
}
},
fields: [
{
name: "input1-1",
label: "input1-1",
render: "input"
},
{
name: "input1-2",
label: "input",
render: "input"
}
]
},
{
name: "group2",
container: {
type: "card",
props: {
title: "group2"
}
},
fields: [
{
name: "input2-1",
label: "input2-1",
render: "input"
}
]
}
];
Table 表格 →