# 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

表单初始值远程请求配置

示例:

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 实例提供的方法

更多实例方法,可查看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

表单项控件

示例:

// 配置化方法写法
render: (ctx) => {
  return <Input disabled={ctx.disabled} />
}

// 配置化属性写法
render: {
  type: 'input',
  props: {
    placeholder: 'Please input',
  }
}

# viewRender

表单 mode 为 view 模式时,优先 viewRender,未配置则使用 render,写法同render

# editRender

表单 mode 为 edit 模式时,优先 editRender,未配置则使用 render,写法同render

# rules

  • 类型:Array<Rule>
  • 默认值: -

校验规则

tips

  • 其中 validator 支持配置化写法,参数 ctx 请查看ctx
  • 校验插件请查看validator

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

表单项远程数据源

示例:

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"
      }
    ]
  }
];
Last Updated: 2020/3/10 下午9:40:21