@beisen-phoenix/form

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' &#124 '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, values: Object, ctx: FormCore) => void

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, core: any) => void
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 方法