# xrc-form2

**Repository Path**: yansen_zh/xrc-form2

## Basic Information

- **Project Name**: xrc-form2
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2019-12-16
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# xrc-form2
基于 [antd v4](https://ant.design/components/form-cn/) 版本进行的 form 组件封装，实现简单的 form 表单 json 配置化

## 引用
```jsx
import {XForm, XItem} from '@zjxpcyc/xrc-form2'
```

## 使用
### 创建 Form

```jsx

// 这样就可以使用 Form 了
class MyComponent extends React.Component {
  render() {
    return (
      <XForm onSubmit={xxx}></XForm>
    );
  }
}

```

生成的 Form 有如下 Props 设置

| prop | 说明 | 类型 |
|---|---|---|
| onSubmit | 表单提交 | function(allFieldValues, setSubmittingFunc), setSubmittingFunc 可以设置提交状态 `true|false` |
| onCancel | 表单取消 | function() {} |
| onError | 表单校验出错 | function(err) {} |
| footer | 表单底部 action 区域 | React.Element , 如果为 `null` 则不显示, 默认带有 `submit` 跟 `cancel` 按钮 |
| ... | 其他 [Antd Form](https://ant.design/components/form-cn/#Form) 支持的属性 |  |

### 添加表单字段

```jsx
import React from 'react';
import { Input } from 'antd';

const fields = [
  {
    label: '姓名',
    name: 'userName',
    render: <Input/>,
    help: '请填写您注册时的手机号或者邮箱',
    required: true,
  },
  {
    label: '密码',
    name: 'userPassword',
    render: <Input.Password placeholder="请输入密码" />,
    required: true,
  },
];


// some codes
// <Form onSubmit={xxx} fields={fields}></Form>

```

表单字段是通过 `json` 配置实现的。支持的属性有

| 属性 | 说明 | 类型 |
|---|---|---|
| render | 字段节点，比如 `input` `select` 之类 | `React.node`, 非必填 |
| ... | 其他 [Form.Item](https://ant.design/components/form-cn/#Form.Item) 支持的属性 |  |


## 示例
请参考 `example` 目录内容

## Q&A
* 隐藏字段

部分场景下, 可能希望提交的 `values` 里面包含隐藏的字段, 这种情况下可以使用
```jsx
{
  name: 'hide-field-name',
  render: null,
  style: { display: none }, // style 跟 noStyle 二选一
  noStyle: true,  // noStyle 为 Form.Item 支持的属性
}
```

* 动态字段

还有一种情况, 某个字段可能因为另外一个字段的设置而显示或者隐藏, 这种情况也可以通过 `style` 与 `noStyle` 来控制.
只不过需要监听字段的修改.

字段的修改有两种方法，一种是监听 `Form.onChange` , 一种是监听 `Form.onValuesChange` .
两者的区别是, 前者实际上是表单字段的 `onChange` 事件代理,  后者是封装过的特殊 `change` 事件，除了提供字段的 `value` 之外，还提供了整个 `Form` 的 `values` 。所以推荐监听 `Form.onValuesChange` 

```jsx
const handleFormChange = (value, allValues) => {
  setFormValues(allValues) // setFormValues 用来缓存最新的表单内容
}


const fields = [
  {
    label: '姓名',
    name: 'userName',
    render: <Input placeholder="请填写您注册时的手机号或者邮箱"/>,
    help: '请填写您注册时的手机号或者邮箱',
    required: true,
  },
  {
    label: ' ',
    colon: false,
    render: '此行文本会随着姓名的输入而显示',
    style: { display: formValue.userName ? undefined : 'none' },  // formValue 就是表单的最新值
  }
]

<XForm fields={fields} onValuesChange={handleFormChange}></XForm>
```

* 级联选择

处理的方式跟动态字段的处理方式基本一致

* 初始化值

两种方式, 一种是把初始化值对象直接放到 `Form.initialValues`

```jsx

const initialValues = { userId: '123', userName: 'foo' }

<XForm initialValues={initialValues} xxx />
```

另一种方式是将初始化 `value` 放入到每个 `field` 里面

```jsx

const fields = [
  {
    label: '姓名',
    name: 'userName',
    value: 'foo',   // 可以用来初始化数据
    render: <Input placeholder="请填写您注册时的手机号或者邮箱"/>,
    help: '请填写您注册时的手机号或者邮箱',
    required: true,
  },
  ...
]

```


## 注意事项
* 字段组件支持自定义封装, 但是封装组件必须满足2个条件。1、值传递通过 `value` 属性, 2、提供 `onChange` 事件
* 字段组件必须支持 `ref` 传递. 因此函数式组件, 请使用 `React.forwardRef` 包裹起来