uxcore-form
v6.3.6
Published
form component for uxcore
Downloads
217
Readme
React Form
setup develop environment
$ git clone https://github.com/uxcore/uxcore-form
$ cd uxcore-form
$ npm install
$ npm start
Usage
see demo/FormDemo.js for details 每一个 field 需要按照 Form -> FormRow -> FormField 的方式进行嵌套,允许 Form -> FormField 的嵌套,会自动增加 FormRow 这一层,并默认占一整行。
API
Form
getValues(force) 获取目前的 values 和 pass(是否通过检测)。 参数:
- force
Boolean
: 强制校验或不校验,undefined 时则忽略此配置。
- force
resetValues() 重置所有的 FormField,如果有默认值则重置为默认值。
setValues(data) 手动设置各个 FormField 的值,在表单联动时可能会用得到。 参数:
- data
Object
: 和 jsxvalues 的格式相同。
- data
isDirty() 获取目前的表单是否没有通过检测,返回 true 或 false。
doValidate(force, always) 获取目前的表单是否通过检测,返回 true 或者 false。
- force:是否强制校验,无视不校验的规则。
- always:强制校验通过或者失败,通常可以用于清空出错状态。
doValidateAndScroll(force, always) 获取目前的表单是否通过检测并滚动至第一个出错的 field,参数同上。
Form.createFormField(options)
|Name |Type |Require |Default |Since Ver. |Note |
|--- |--- |--- |--- |--- |---|
|options.component |React Element |yes |input |1.8.12 |被包裹的组件,需要提供 value 和 onChange,或相同功能的 API |
|options.valuePropName |string |No |value |1.8.12 |与 value 对应的 prop 名字 |
|options.changePropName |string |No |onChange |1.8.12 |与 onChange 对应的 prop 名字|
|options.processValue |func(value, ...other) |No | - |1.8.12 |针对 value(editKey 对应字段)的处理函数|
|options.renderView |func(value) |No | val => JSON.stringify(val)
|1.8.12 |定制化渲染 view 状态|
props
Form
| 配置项 | 类型 | 必填 | 默认值 | 功能/备注 | |---|---|---|---|---| |className|string|optional|""|加入额外的类名,在使用 kuma 的基础上进行适当的定制时会用得到| |jsxprefixCls|string|optional|"kuma-form"|默认类名,用户可以通过修改此项来完成样式的定制| |jsxmode|string|optional|"EDIT"|Form 编辑和只读模式,传值方式见 demo| |jsxvalues|object|optional|-|传入表单的初始值,格式见 Usage,每一个 key 与 formField 中的 jsxname 相对应,注意是初始值,不要把 onChange 中的变化同步到这里| |jsxonChange|function(values, name, pass)|optional|noop|当表单中值有变化时触发,传回 values,格式同 jsxvalues,同时传回发生变化的表单域的 name,以及该表单域是否通过校验| |instantValidate|boolean|optional|true|是否开启即时校验| |asyncValidate|boolean|optional|false|是否开启异步校验模式,目前仅支持全局配置| |verticalAlign|boolean|optional|false|表单域是否竖排| |size|string|optional|large|尺寸,支持 large、middle、small|
jsxvalues 的格式
{
jsxname1: value1,
jsxname2: value2
}
FormRow
| 配置项 | 类型 | 必填 | 默认值 | 功能/备注 | |---|---|---|---|---| |className|string|optional|""|加入额外的类名,在使用 kuma 的基础上进行适当的定制时会用得到| |jsxprefixCls|string|optional|"kuma-form-row"|默认类名,用户可以通过修改此项来完成样式的定制|
FormField 通用配置
| 配置项 | 类型 | 必填 | 默认值 | 功能/备注 | |---|---|---|---|---| |className|string|optional|""|加入额外的类名,在使用 kuma 的基础上进行适当的定制时会用得到| |jsxshow|bool|optional|true|是否显示该表单域,不显示的表单域将不占宽度| |jsxmode|string|optional|"EDIT"|FormField 的编辑和只读模式,优先级高于 Form,传值方式见 demo| |jsxshowLabel|bool|optional|true|是否显示 label| |jsxname|string|required|-|表单字段,返回值时该字段将作为 key| |jsxlabel|string|required|-|左侧的说明文字,不写即为留白| |jsxprefixCls|string|optional|"kuma-form-field"|默认类名,用户可以通过修改此项来完成样式的定制| |jsxflex|number|optional|1|占 FormRow 宽的比例,类似于 css3 中的 flex-box| |jsxtips|string|optional|""|说明文字| |jsxrules|object/array|optional|-|validators,具体用法和格式见 Usage,Form 已经提供了一些现成的 validator 供使用。也可以自己编写| |instantValidate|boolean|optional|true|是否开启即时校验| |verticalAlign|boolean|optional|false|表单域是否竖排| |inputBoxMaxWidth|string|optional| - | 泛指的输入框的最大宽度,通常用于较宽页面 |
Validators
Form 提供了一些通用的 validator,通过 Form.Validators 来引入。用法还是见 Usage 和
demo/formDemo.js
包括: 所有的 validator 返回 true,表示通过。 validator 也可以自己定义,会传入相应的表单值,根据判断,返回 true,表示通过。
- isNotEmpty
- isNum
- isInt: 是否是整数
- isDecimal: 是否是小数
- isArray
- isRegExp
- isObject
- isFunc
- isEmail
- isUrl
- isHex
- isIdCard: 是否是中国身份证。
- isCNMobile: 是否是中国手机号。
FormField 专属配置
所有的 FormField 都共享通用配置,所有的专属配置在
demo/formDemo.js
,均有体现。
InputFormField
| 配置项 | 类型 | 必填 | 默认值 | 功能/备注 | 版本 | |---|---|---|---|---|---| |jsxplaceholder|string|optional|""|占位符|-| |jsxdisabled|boolean|optional|false|disable 状态|-| |validateOnBlur|boolean|optional|false|验证是否是在 blur 的时候出发,默认情况是在 change 时触发,此项为 true 后,onChange 的 pass 永远为 true,相对应的 onBlur 的 pass 会随之变化|1.2.10| |onKeyDown|function(e)|optional|noop|监听键盘事件| |onBlur|function(e, pass)|optional|noop|输入框 blur 时触发,第二个参数为验证是否通过,若 validateOnBlur 为 false,则 pass 永远为 true|1.2.10| |onFocus|function(e)|optional|noop|输入框获取焦点时触发|1.2.10| |renderView|function(value)|optional|noop|自定义渲染 view 状态,参数是默认渲染的值|1.6.0| |autoTrim|boolean|optional|-|自动去除值两端的空格|1.2.12| |inputType|string|optional|'text'|input 的 type,目前支持 "text" 和 "password"|1.2.23|
插件:
- Count,通过 InputFormField.Count 取得,一个内置的计数器,用法如下:
<InputFormField> <Count total="20"> </InputFormField>
- LeftAddon/RightAddon,通过 InputFormField.LeftAddon/InputFormField.RightAddon 取得,给 input 左侧加入自定义的图标或文字,用法如下:
<InputFormField> <LeftAddon> <i className="kuma-icon kuma-icon-phone"></i> </LeftAddon> <RightAddon> <span>元</span> </RightAddon> </InputFormField>
TextAreaFormField
| 配置项 | 类型 | 必填 | 默认值 | 功能/备注 | |---|---|---|---|---| |jsxplaceholder|string|optional|""|占位符| |validateOnBlur|boolean|optional|false|验证是否是在 blur 的时候出发,默认情况是在 change 时触发,此项为 true 后,onChange 的 pass 永远为 true,相对应的 onBlur 的 pass 会随之变化|1.2.11| |onKeyDown|function(e)|optional|noop|监听键盘事件| |onBlur|function(e, pass)|optional|noop|输入框 blur 时触发,第二个参数为验证是否通过,若 validateOnBlur 为 false,则 pass 永远为 true|1.2.11| |onFocus|function(e)|optional|noop|输入框获取焦点时触发|1.2.11| |autoTrim|boolean|optional|-|自动去除值两端的空格|1.2.12| |autosize|boolean|optional|true|根据内容自动撑开(IE8 下无效)|1.3.10|
配置 autosize 的同时,还可以通过样式指定 min-height 和 max-height
插件:
- Count,通过 TextAreaFormField.TextAreaCount 取得,一个内置的计数器,用法如下:
<TextAreaFormField> <TextAreaCount total={100}> </TextAreaFormField>
RadioGroupFormField
| 配置项 | 类型 | 必填 | 默认值 | 功能/备注 | |---|---|---|---|---| |jsxdisabled|boolean|optional|false|disable 状态|
- Item:通过 RadioGroupFormField.Item 取得,有两个 props
- value
- text:显示的值
- 使用方式:
<RadioGroupFormField>
<Item value="1" text="a">
<Item value="2" text="b">
<Item value="3" text="c">
</RadioGroupFormField>
SelectFormField
| 配置项 | 类型 | 必填 | 默认值 | 功能/备注 | |---|---|---|---|---| |jsxdata|object|optional|-|传入用于生成列表的数据,格式为{value: text}| |jsxfetchUrl|string|optional|-|如果 Select 是通过搜索异步获取选项,则需要填入此项| |jsxstyle|obj|optional|-|与 react 传入 style 的方式相同,修改选择框的样式| |beforeFetch|func|optional|-|会传入 {q: value}, value 为搜索框中变化的值,在发出 ajax 请求之前,将数据处理为应该发送的格式,并需返回该数据。| |afterFetch|func|optional|-|会传入返回的数据, 将其处理为 jsxdata 的格式并返回| |dataType|string|optional|'json'|发送 ajax 请求的类型|
jsxdata 的格式
jsxdata 目前支持两种格式
// Object
{
a: "A",
b: "B"
}
// Array
[
{
value: 'a',
text: 'A'
}
]
配置 jsxfetchUrl 后,会在组件渲染后立刻以空搜索值发起一次请求,我们强烈建议服务端完善空值搜索的请求处理逻辑,返回热点数据和用户关联数据,以提供更好的选择体验。
此外,SelectFormField 还支持 uxcore-select2 除 onSelect/onDeselect 外的全部属性。
SearchFormField
| 配置项 | 类型 | 必填 | 默认值 | 功能/备注 |
|---|---|---|---|---|
|advancedOptions|array|optional|-|右侧高级选项的选择项:格式为[{value: xxx, text: xxx}]
|
|advancedConfig|object|optional|-|右侧高级选项的配置,同 uxcore-select2
|
|classOptions|array|optional|-|左侧类别选项的选择项:格式为[{value: xxx, text: xxx}]
|
|classConfig|object|optional|-|左侧类别选项的配置,同 uxcore-select2
|
|tidy|bool|optional|-|精简模式|
|onIconClick|function(e)|optional|-|点击搜索图标触发回调|
该组件继承自 SelectFormField,支持 SelectFormField 的全部 props。
CheckboxGroupFormField
| 配置项 | 类型 | 必填 | 默认值 | 功能/备注 | |---|---|---|---|---| |jsxdisabled|boolean|optional|false|disable 状态|
- Item:通过 CheckboxGroupFormField.Item 取的,有两个 props
- value
- text:显示的值
- disabled:该 Item 的 disable 状态。
- addon: 额外指定的信息,例如tips
- 使用方式:
<CheckboxGroupFormField>
<Item value="1" text="a" disabled={true} />
<Item value="2" text="b" />
<Item value="3" text="c"
addon={
<Tooltip overlay={<div>提示</div>}>
<i className='kuma-icon kuma-icon-caution' style={{color: 'blue', fontSize: '12px', 'marginLeft': '3px'}} />
</Tooltip>
}
/>
</CheckboxGroupFormField>
DateFormField
| 配置项 | 类型 | 必填 | 默认值 | 功能/备注 | |---|---|---|---|---| |jsxtype|string|optional|single|single/cascade 单独、级联| |jsxfrom|string|optional|-|开始日期| |jsxto|string|optional|-|结束日期| |panel|string|optional|"day"|何种面板,枚举值为"month","year"和"day"| |autoMatchWidth|boolean|optional|false|从 1.8.11 版本支持,在级联状态下输入框自动匹配宽度|
除此之外,支持除 onSelect,uxcore-calendar 的所有 props。
NumberInputFormField
| 配置项 | 类型 | 必填 | 默认值 | 功能/备注 |
|---|---|---|---|---|
|jsxplaceholder|string|optional|""|占位符|
|jsxtype|string|optional|""|目前支持 "money", "cnmobile" 和 "card", 提供三种格式化显示的方法。"money"的格式为123 121 121.213 121
,"cnmobile"的格式为 86 1565 7263 8223
, "card" 的格式为 3321 3123 3243 4343
|
|fixedNum|number|optional| - | 锁定小数位 |
|delimiter|string|optional| ' ' | 分隔符 |
|formatOnBlur|bool|optional| false | 在失焦时进行格式化(6.2.0 后支持) |
CascadeSelectFormField
| 配置项 | 类型 | 必填 | 默认值 | 功能/备注 | |---|---|---|---|---| |jsxdata|object|required|-|级联选择框,只支持直接传入 data 初始化,格式见 Usage 中的 casData,length 为必须传的 key,告诉 field 有几层级联。| |jsxplaceholder|string|optional|"请下拉选择"|占位符| |jsxstyle|object|optional|-|与 react 传入 style 的方式相同,修改选择框的样式| |getPopupContainer|function():React Element|optional| - | 弹出的菜单渲染在哪个容器中,需返回一个 DOM Node|
PickableFormField
| 配置项 | 类型 | 必填 | 默认值 | 功能/备注 | |---|---|---|---|---| |multiple|boolean|optional|true|是否支持多选| |value|string/number|required|-|pickable Item 对应的值| |type|string|optional|normal|样式风格,可选值为normal,simple,hook| |max|number|optional|99|最大显示的数字,超过 max,显示 max+|
EditorFormField
| 配置项 | 类型 | 必填 | 默认值 | 功能/备注 | |---|---|---|---|---| |placeholder|string|optional|""|占位符| |jsxcontent|string|optional|""|已废弃,默认值直接通过 Form 的 jsxvalues 即可传递| |jsxconfig|object|optional|{}|用户自定义的配置项,tinyMCE 的配置项,官方文档中所有 init 部分的配置在这里完成,详细见 http://www.tinymce.com/wiki.php/Configuration|
API
setContent(content):设置 EditorFormField 的值,很不幸,EditorFormField 无法做成完全受控的组件,因为 setContent 操作会导致搜狗等中文输入法使用障碍,因此 EditorFormField 的值重置通过这个 API 来完成,或者也可以使用 Form 的 setValues 方法。
OtherFormField
OtherFormField 是一个特殊的 FormField,它用来和其他 FormField 一起完成布局(比如在一行排列等),如果需要一些装饰类的东西,可以以子元素的形式传入到这个 Field 里。 他也可以用于布局中的占位。
ButtonGroupFormField
ButtonGroupFormField 是一个特殊的 FormField,它用来生成一些特定的表单按钮,这是为了与 Grid 相结合而准备的。如果需要自定义一些按钮,请使用 OtherFormField 和 uxcore-button 相结合来使用。 你可以像这样使用它:
var Button = require('uxcore-button');
<ButtonGroupFormField>
{// handleClick 会被传入一个参数 data,取得的值和 API getValues() 相同}
<Button action="submit" onClick={this.handleClick.bind(this)}/>
{// 目前只支持 submit 和 reset 两种 action}
<Button action="reset"/>
</ButtonGroupFormField>