---

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 时则忽略此配置。

• resetValues() 重置所有的 FormField，如果有默认值则重置为默认值。

• setValues(data) 手动设置各个 FormField 的值，在表单联动时可能会用得到。 参数：

  • data Object: 和 jsxvalues 的格式相同。

• 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 会随之变化
onKeyDown	function(e)	optional	noop	监听键盘事件
onBlur	function(e, pass)	optional	noop	输入框 blur 时触发，第二个参数为验证是否通过，若 validateOnBlur 为 false，则 pass 永远为 true
onFocus	function(e)	optional	noop	输入框获取焦点时触发
autoTrim	boolean	optional	-	自动去除值两端的空格
autosize	boolean	optional	true	根据内容自动撑开(IE8 下无效)

配置 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, value)	optional	-	点击搜索图标触发回调, value 是 Field 的值，回传方便在 standalone 方式下使用，格式为 { main, class, advanced }，对应主输入区文本、类别值（如果有）、高级选项值（如果有）

该组件继承自 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>