form-render-yanxi

FormRender

一站式中后台表单解决方案

官网

https://xrender.fun/form-render

FormRender 1.0 是下一代的 React.js 表单解决方案。项目从内核级别进行了重写，为了能切实承接日益复杂的表单场景需求。我们的目标是以强大的扩展能力对表单场景 100%的覆盖支持，同时保持开发者能快速上手，并以表单编辑器、插件、自定义组件等一系列周边产品带来极致的开发体验。在开发 1.0 的道路上，我们做了一系列的取舍，详见0.x - 1.0 迁移文档

安装

FormRender 依赖 ant design，单独使用不要忘记同时安装 antd

npm i form-render --save

使用

最简使用 demo：

import React from 'react';
import { Button } from 'antd';
import FormRender, { connectForm } from 'form-render';

const schema = {
  type: 'object',
  properties: {
    input1: {
      title: '简单输入框',
      type: 'string',
      required: true,
    },
    select1: {
      title: '单选',
      type: 'string',
      enum: ['a', 'b', 'c'],
      enumNames: ['早', '中', '晚'],
    },
  },
};

class Demo extends React.Component {
  render() {
    const { form } = this.props;
    return (
      <div>
        <FormRender form={form} schema={schema} />
        <Button type="primary" onClick={form.submit}>
          提交
        </Button>
      </div>
    );
  }
}

export default connectForm(Demo);

对于函数组件，FormRender 提供了 useForm hooks, 书写更为灵活

import React from 'react';
import { Button } from 'antd';
import FormRender, { useForm } from 'form-render';

const schema = {
  type: 'object',
  properties: {
    input1: {
      title: '简单输入框',
      type: 'string',
      required: true,
    },
    select1: {
      title: '单选',
      type: 'string',
      enum: ['a', 'b', 'c'],
      enumNames: ['早', '中', '晚'],
    },
  },
};

const Demo = () => {
  const form = useForm();
  return (
    <div>
      <FormRender form={form} schema={schema} />
      <Button type="primary" onClick={form.submit}>
        提交
      </Button>
    </div>
  );
};

export default Demo;

从 demo 中我们不难发现 FormRender 的一些设计：

1. 以 schema 来描述表单展示，提交方式与 antd v4 的方式类似
2. schema 以国际标准的 JSON schema 为基础，同时能够方便使用任何 antd 的 props
3. 通过 bind 字段，我们允许数据的双向绑定，数据展示和真实提交的数据可以根据开发需求不同（例如从服务端接口拿到不规则数据时，也能直接使用）
4. 可以通过displayType,labelWidth等字段轻易修改展示

组件 Props

import Form, { useForm, connectForm } from 'form-render';

<Form /> (常用 props)

参数	描述	类型	是否必填	默认值
id	表单的 id，一般用于标识一个表单的语义化名称	string/number	否
schema	描述表单的 schema，详见	object	是
form	useForm创建的表单实例，与 Form 一对一绑定	FormInstance	是
onFinish	提交后的回调，执行 form.submit() 后触发	(data, errors: Error[]) => void	否	() => {}
beforeFinish	在 onFinish 前触发，一般用于外部校验逻辑的回填，入参是个对象，便于扩展	({ data, errors, schema, ...rest }) => Error[] 或 Promise<Error[]>	否	() => {}
onMount	表单首次加载时触发，详见生命周期	() => void	否	() => {}
displayType	表单元素与 label 同行 or 分两行展示, inline 则整个展示自然顺排	string('column' / 'row' / 'inline')	否	'column'
labelAlign	label 标签的文本对齐方式	string('left' / 'right')	否	'right'
colon	表示是否显示 label 后面的冒号	boolean	否	true
widgets	自定义组件，当内置组件无法满足时使用	object	否	{}
watch	类似于 vue 的 watch 的用法，详见表单监听 & 回调	object	否	{}
removeHiddenData	提交数据的时候是否去掉已经被隐藏的元素的数据，默认不隐藏	boolean	否	true
debug	开启 debug 模式，时时显示表单内部状态，开发的时候强烈建议打开	boolean	否	false
readOnly	只读模式，一般用于预览展示，全文 text 展示	boolean	否	false

注 1：

<Form /> (不常用 props)

参数	描述	类型	默认值
className (v.1.6.12)	顶层 className	string	''
style (v.1.6.12)	顶层 style	object	{}
column	一行展示多少列	number	1
mapping	schema 与组件的映射关系表，当内置的表不满足时使用	object	{}
disabled	禁用模式，全部表单元素禁用	boolean	false
debugCss	用于 css 问题的调整，显示 css 布局提示线	boolean	false
locale	展示语言，目前只支持中文、英文	string('cn'/'en')	'cn'
configProvider	antd 的 configProvider，配置透传	object	-
allCollapsed	对象组件是否默认折叠（全局）	boolean	false
debounceInput	是否开启输入时使用快照模式。仅建议在表单巨大且表达式非常多时开启	boolean	false
validateMessages	修改默认的校验提示信息。详见下	object	{}

validateMessages

Form 为验证提供了默认的错误提示信息，你可以通过配置 validateMessages 属性，修改对应的提示模板。一种常见的使用方式，是配置国际化提示信息：

const validateMessages = {
  required: '${title}是必选字段',
  // ...
};

<Form validateMessages={validateMessages} />;

目前可以用的转义字段为 ${title}/${min}/${max}/${len}/${pattern}, 如果有更多需求请提 issue

useForm / connectForm

useForm / connectForm 用于创建表单实例，所有对表单的外部操作和回调函数全挂在其生产的实例上,例如表单提交是 form.submit。注意 useForm 是 hooks，而 connectForm 是高阶组件，所以前者只能在函数组件使用，后者可用于 class 组件。两者无其他区别。使用时需要创建实例，并通过 props 挂钩到与其对应的表单上：

import Form, { useForm } from 'form-render';

const Demo = () => {
  const form = useForm();
  return <Form form={form} schema={...} />;
};

import Form, { connectForm } from 'form-render';

const Demo = ({ form }) => {
  return <Form form={form} schema={...} />;
};

export default connectForm(Demo);

form 方法

参数	描述	类型
submit	触发提交流程，一般在提交按钮上使用	() => void
resetFields	清空表单（也会清空一些内置状态，例如校验）	({formData?: any, submitData?: any, errorFields?: Error[], touchedKeys?: any[], allTouched?: boolean}) => void
errorFields	表单校验错误的数组	array,[{name, error: []}]
setErrorFields	外部手动修改 errorFields 校验信息，用于外部校验回填	(error: Error[]) => void
setValues	外部手动修改 formData，用于已填写的表单的数据回填	(formData: any) => void
onItemChange	外部修改指定单个 field 的数据	(path: string, value: any) => void
getValues	获取表单内部维护的数据 formData	() => void
schema	表单的 schema	object
touchedKeys	已经触碰过的 field 的数据路径	string[]
removeErrorField	外部手动删除某一个 path 下所有的校验信息	(path: string) => void
formData	表单内部维护的数据，建议使用 getValues/setValues	object