@beisen-phoenix/form NPM

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, 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 方法

@beisen-phoenix/alert @beisen-phoenix/button @beisen-phoenix/grid @beisen-phoenix/icon @beisen-phoenix/style-token @beisen-phoenix/tooltip async-validator deep-equal

4 years ago

4 years ago

4 years ago

4 years ago

4 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

Change Log

2019-06-18 v1.0.4

2019-06-18 v1.0.3

一、简介

1. 主要功能

2. 核心对象

3. 组件状态

4. 字段组件接口

二、Quick Start

📦 安装

🔨 使用

三、API

1. FormCore 对象 成员

属性

方法

事件

2. FormCoreConfig 对象 成员

属性

事件

3. Form 表单组件 成员

属性

事件

4. FormItem 表单字段组件 成员

属性

事件

四、常见问题

1. FormCore 对象成员

2. FormCoreConfig 对象成员

3. Form 表单组件成员

4. FormItem 表单字段组件成员