API Props

order: 1 group: order: 6 title: API

toc: content

Props

FormInstance

react 更新机制导致，同时多次调用 setSchemaByPath 无效，所以请使用 setSchema，事实上setSchema 能完全覆盖 setSchemaByPath 的场景。

Widgets

当内置组件不能满足需求时，可以传入自定义组件。

```jsx | pure import { Cascader } from ‘antd’;

// 顶层引入注册

// schema 中使用 location: { title: ‘省市区’, type: ‘string’, widget: ‘cascader’, },

### Watch
用于数据的监听的唤起回调。语法类似于 vue 的 `watch`。
```tsx | pure
type WatchProperties = Record<
  Path,
  (val: any) => void | {
    handler: (val: any) => void;
    immediate?: boolean; // 是否在首次加载时就执行一次 watch 的 handler
  }
>;
const watch: WatchProperties = {
  '#': val => {
    // # 为全局
    console.log('表单的实时数据为：', val);
  },
  path1: val => {
    // do something ...
  },
  path2: {
    handler: val => {},
    immediate: true,
  },
};
<Form watch={watch} />;

ValidateMessages

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

```jsx | pure const validateMessages = { required: ‘${title}是必选字段’, // … };

目前可以用的转义字段为 `${title}`，`${min}`，`${max}`，`${len}`，`${pattern}`, 如果有更多需求请提 [issue](https://github.com/alibaba/x-render/issues/new/choose)。
### Path
`path` 代表一个表单项在 schema 中的路径，在调用 `form.setSchemaByPath`，`watch` 等 api 时，需要用到。
```js
const schema = {
  type: 'object',
  properties: {
    // 没有嵌套元素的普通表单中
    // 此元素的 path 为 'address'
    address: {
      title: '地址',
      type: 'string',
    },
    // 表单中嵌套了一个对象类型的元素时
    obj: {
      title: '对象',
      type: 'object',
      properties: {
        // 此元素的 path 为 'obj.select'
        select: {
          title: '单选',
          type: 'string',
          enum: ['a', 'b', 'c'],
          enumNames: ['早', '中', '晚'],
        },
      },
    },
    // 在 list 类型的表单元素中，使用 [] 表示 list
    list: {
      title: '对象数组',
      type: 'array',
      items: {
        type: 'object',
        properties: {
          // 此元素的 path 为 'list[].input'
          input: {
            title: '输入框',
            type: 'string',
          },
          object: {
            title: '对象',
            type: 'object',
            properties: {
              // 此元素的 path 为 'list[].object.select'
              select: {
                title: '选择框',
                type: 'string',
                enum: ['a', 'b', 'c'],
                enumNames: ['早', '中', '晚'],
              },
            },
          },
        },
      },
    },
  },
};

Error

type Error = {
  /** 错误的数据路径 */
  name: string;
  /** 错误的内容 */
  error: string[];
};

Hooks

UseForm

useForm 用于创建表单实例，使用时需要创建实例，并传入与其对应的表单上。

```jsx | pure import Form, { useForm } from ‘form-render’;

const Demo = () => { const form = useForm(); return

如果是 class 组件可以使用 `connectForm` ，作用与 `useForm` 相同。
```jsx | pure
import Form, { connectForm } from 'form-render';
const Demo = ({ form }) => {
  return <Form form={form} />;
};
export default connectForm(Demo);

useForm 可以传入以下参数，详见表单健康度 & 提效。

jsx | pure const form = useForm({ logOnMount: info => {}, // 会在表单首次加载时触发, 获取表单信息 logOnSubmit: info => {}, // 会在 form.submit 时触发，获取表单信息（如填写时长、报错信息等） });