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