# @zjxpcyc/xrc-form2

> 基于 Antd Form 封装的 JSON 可配置表单

Latest version **3.0.2** (published 2020-03-19) · MulanPSL license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install @zjxpcyc/xrc-form2
pnpm add @zjxpcyc/xrc-form2
yarn add @zjxpcyc/xrc-form2
bun add @zjxpcyc/xrc-form2
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 3.0.2 |
| Published | 2020-03-19 |
| First published | 2019-12-16 |
| Weekly downloads | 0 |
| License | MulanPSL |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 77.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | yansen |
| Maintainers | yansen_zh |
| Keywords | form, json, antd form |

## Links

- npm: https://www.npmjs.com/package/@zjxpcyc/xrc-form2
- Repository: https://gitee.com/yansen_zh/xrc-form2
- npm.io page: https://npm.io/package/@zjxpcyc/xrc-form2

## Dependencies (3)

- [antd](https://npm.io/package/antd.md) ^4.0.2
- [react](https://npm.io/package/react.md) ^16.13.0
- [prop-types](https://npm.io/package/prop-types.md) ^15.7.2

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 3.0.2 (latest) — 2020-03-19
- 3.0.1 — 2020-03-11
- 3.0.0 — 2020-03-10
- 2.2.2 — 2020-03-01
- 2.2.1 — 2019-12-24
- 2.2.0 — 2019-12-24
- 2.1.0 — 2019-12-17
- 2.0.0 — 2019-12-16

## 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` 包裹起来

---
_Source: https://npm.io/package/@zjxpcyc/xrc-form2 · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._