README
Phoenix Form 表单组件
接口友好,高效接入
Change Log
2019-06-18 v1.0.4
- validateTrigger 支持在 FormItem 上配置,实现不同字段使用不同验证触发时机的效果。优先级高于 FormCore 上的全局配置
2019-06-18 v1.0.3
- 添加 validateTrigger 属性,支持配置验证触发时机
- 将 autoValidate 标记为即将过期接口
❓ 问题反馈:http://gitlab.beisencorp.com/ux-phoenix/form/issues
一、简介
1. 主要功能
- 数据收集
- 数据展示
- 数据验证
2. 核心对象
- FormCore 对象:使用该对象与表单交互,进行数据获取,数据验证等操作
- Form 组件:写在 JSX 中的表单组件
- FormItem 组件:写在 JSX 中的表单字段组件
3. 组件状态
- 表单状态(Status)包含以下三种:edit(编辑态), preview(预览态), disabled(禁用态)。
- 状态层级,包含以下两种:Form(表单全局级别),FormItem(字段级别)。
- 字段级别默认继承全局级别的状态,除非为字段制定了专门的字段级状态。
4. 字段组件接口
- value:【必要】传给字段组件的值
- hasError:字段验证失败时,传给字段组件该属性为 true
- disabled:字段禁用时,传给字段组件该属性为 true
- onChange:【必要】字段组件值改变时抛出的事件
- onBlur:字段组件失去焦点时抛出的事件
- onFocus:字段组件获得焦点时抛出的事件
- onKeyUp:字段组件键盘事件
二、Quick Start
📦 安装
npm install @beisen-phoenix/form
🔨 使用
// 基础使用
import Form, { FormCore, FormItem } from '@beisen-phoenix/form';
let core = new FormCore();
return (
<Form core={core}>
<FormItem label={'用户名'} name={'username'}>
<input />
</FormItem>
</Form>
);
// 获取数据
import Form, { FormCore, FormItem } from '@beisen-phoenix/form';
let core = new FormCore();
return (
<>
<Form core={core}>
<FormItem label={'用户名'} name={'username'}>
<input />
</FormItem>
</Form>
<button
onClick={() => {
console.log(core.getValues());
}}
>
GetValues
</button>
</>
);
// 设置数据
import Form, { FormCore, FormItem } from '@beisen-phoenix/form';
let core = new FormCore();
return (
<>
<Form core={core}>
<FormItem label={'用户名'} name={'username'}>
<input />
</FormItem>
</Form>
<button
onClick={() => {
core.setValues({ username: 'KXLF' });
}}
>
SetValue
</button>
</>
);
// 数据验证
import Form, { FormCore, FormItem } from '@beisen-phoenix/form';
let core = new FormCore();
let validateConfig = {
username: { required: true, message: '请填写用户名' }
};
return (
<>
<Form core={core} validateConfig={validateConfig}>
<FormItem label={'用户名'} name={'username'}>
<input />
</FormItem>
</Form>
<button
onClick={() => {
core.validateAll();
}}
>
SetValue
</button>
</>
);
// 异步数据验证
import Form, { FormCore, FormItem } from '@beisen-phoenix/form';
let core = new FormCore();
let validateConfig = {
username: {
validator(rule, value, callback) {
// 开始异步验证过程
console.log('异步验证用户名');
setTimeout(() => {
if (value != 'KXLF') {
// 验证失败的回调
callback(['用户名错误!']);
} else {
// 验证成功的回调
callback([]);
}
}, 1000);
}
}
};
return (
<>
<Form core={core} validateConfig={validateConfig}>
<FormItem label={'用户名'} name={'username'}>
<input />
</FormItem>
</Form>
<button
onClick={() => {
core.validateAll();
}}
>
SetValue
</button>
</>
);
- 验证规则配置,请参考:https://github.com/yiminghe/async-validator
三、API
- 注:FormItem 的状态 Status 包含:'edit' | 'preview' | 'disable'
1. FormCore 对象 成员
属性
属性名 | 说明 | 类型 | 必须配置 | 默认值 |
---|---|---|---|---|
globalStatus | 表单全局状态 | Status | 否 | 'edit' |
status | 表单各个字段的状态 | object {[name]: String, Status} | 否 | |
value | 表单各个字段的值 | object {[name]:any(字段接收的value是什么格式这里就写什么格式 ), any} | 否 | |
autoValidate | 【即将废弃,建议使用 validateTrigger 实现】是否在值变化时,触发校验 | Boolean | 否 | false |
validateTrigger | 验证触发时机,支持的类型有:onChange、onBlur、onFocus、onKeyUp。 | string | Array | 否 | [] |
validateConfig | 验证规则, (若要动态修改,请使用 core.setValidateConfig) | Object | Array | 否 | |
error | 表单的验证失败信息 | object {[name]:String, any} | 否 | |
props | 表单组件属性 | object {[name]:String, object} | 否 |
方法
方法名 | 说明 | 类型 |
---|---|---|
getGlobalStatus | 获取表单全局状态 | Function () => String |
setGlobalStatus | 设置表单全局状态 | Function (String) => void |
getStatus | 获取字段状态 | Function ()=> object {[name]: String, Status} Function (name: String) => Status |
setStatus | 设置字段状态 | Function (status: object {[name]: String, Status}) => void Function (name: String, status: Status) => void |
getValues | 获取所有值 | Function () => object {[name]: String, any} |
getValue | 获取单个字段值 | Function (name: String) => any |
setValues | 设置多个字段值,触发渲染 | Function (values: object {[name]: String, any}) => void |
setValue | 设置单个字段值,触发渲染 | Function (name: String, value: any) => void |
getError | 获取字段错误信息 | Function ()=> object {[name]:String, String} Function (name: String) => String |
setError | 设置字段错误信息,触发渲染 | Function (name: String, message: String)=> void Function (errors: object {[name]: String, String}) => void |
clearError | 清除字段错误信息,触发渲染 | Function (name: String)=> void Function () => void name表示字段的名字,表示清除具体某个字段的错误信息,如果不传任何参数则清空所有字段error |
validateItem | 校验单个字段 | Function (name: String, cb: () => void, opts: Object) => Promise |
validateAll | 校验所有字段 | Function (cb: () => Object) => Promise |
validateWithoutRender | 校验所有字段,不触发渲染 | Function (cb: () => Object) => Promise |
scrollToError | 滚动到第一个错误信息的位置 | Function () => void |
setValidateConfig | 动态设置验证规则 | Function (config: Object) => void |
getProps | 获取 FormItem 属性 | Function (name: String) => object {[name]:String, any} |
setProps | 设置 FormItem 属性 | Function (name: String, props: object {[name]: String, object}) => void |
事件
事件名 | 说明 | 类型 |
---|---|---|
onChange | 字段值变更时触发 | (firekeys: Array |
2. FormCoreConfig 对象 成员
(该对象是在 new FormCore 时传入的配置对象)
属性
属性名 | 说明 | 类型 | 必须配置 | 默认值 |
---|---|---|---|---|
globalStatus | 表单全局状态 | String | 否 | 'edit' |
status | 字段状态 | object {[name]: String, Status} | 否 | |
values | 表单业务数据 | object {[name]: String, any} | 否 | |
validateConfig | 验证规则 | Object | Array | 否 |
事件
事件名 | 说明 | 类型 |
---|---|---|
initialized | 初始化完成的回调函数 | ()=>void |
3. Form 表单组件 成员
属性
属性名 | 说明 | 类型 | 必须配置 | 默认值 |
---|---|---|---|---|
globalStatus | 表单全局状态 | Status | 否 | 'edit' |
status | 表单各个字段的状态 | object {[name]: String, Status} | 否 | |
value | 表单各个字段的值 | object {[name]: String, any} | 否 | |
autoValidate | 【即将废弃,建议使用 validateTrigger 实现】是否在值变化时,触发校验 | Boolean | 否 | false |
validateTrigger | 验证触发时机,支持的类型有:onChange、onBlur、onFocus、onKeyUp。 | string | Array | 否 | [] |
validateConfig | 验证规则, (若要动态修改,请使用 core.setValidateConfig) | Object | Array | 否 | |
error | 表单的验证失败信息 | object {[name]: String, any} | 否 | |
colon | 是否在字段名称后加冒号 | Boolean | 否 | |
layout | 设置布局方式 | ('horizontal' | 'vertical' | 'adaptive-horizontal' | 'adaptive-vertical') | 否 | 'horizontal' |
事件
事件名 | 说明 | 类型 |
---|---|---|
onMount | 组件挂载完毕 | (cb: () => FormCore) => void |
onChange | 字段值发生变化 | (val: Object, fireKey: Array |
onFocus | 字段控件获得焦点 | (name: String) => void |
onBlur | 字段控件失去焦点 | (name: String) => void |
onKeyUp | 字段控件键盘事件 | (event: React.KeyboardEvent) => void |
4. FormItem 表单字段组件 成员
属性
属性名 | 说明 | 类型 | 必须配置 | 默认值 |
---|---|---|---|---|
name | 字段唯一标识名称,不可重复 | String | 否 | 随机 |
value | 字段值 | any | 否 | |
status | 字段状态 | Status | 否 | 'edit' |
error | 字段验证失败信息 | any | 否 | |
props | 字段组件属性 | Object | 否 | |
globalStatus | 表单全局状态 | Status | 否 | 'edit' |
validateTrigger | 验证触发时机,优先级高于 FormCore 上的配置,支持的类型有:onChange、onBlur、onFocus、onKeyUp。 | string | Array | 否 | [] |
validateConfig | 验证规则 | Object | Array | 否 | |
colon | 是否在字段名称后加冒号 | Boolean | 否 | |
labelWidth | 自定义字段标题的宽度,horizontal 布局下默认为 72px | Number | 否 | |
labelHelp | 字段标题右侧的帮助图标 | String | Element | 否 | |
labelHelpLink | 字段标题右侧的帮助图标的链接,有值即为链接,无值即为普通帮助提示 | String | 否 | |
contentHelp | 字段控件的帮助说明 | String | 否 | |
labelAlign | 字段标题水平对齐方式 | 'left' | 'right' | 否 | 'right' |
事件
事件名 | 说明 | 类型 |
---|---|---|
onFocus | 字段控件获得焦点 | (name: String) => void |
onBlur | 字段控件失去焦点 | (name: String) => void |
onKeyUp | 字段控件失去焦点 | (event: React.KeyboardEvent) => void |
四、常见问题
- 一个 Form 对应一个 Core 实例,避免不同 form 之间互相影响
- validateConfig 在组件初始化时使用,若需要动态修改,请使用 Core 实例的 setValidateConfig 方法