How to Build Complex Dynamic Forms with Zan-Form’s Configurable Approach

Background

In frontend development, complex forms with conditional fields often become hard to maintain when built with raw JSX. The article uses a leave‑request form example with gender radio, leave‑type select, and a conditional uploader to illustrate the problem.

Configuration‑Based Solution (zan‑form)

zan‑form is a plugin for the zent UI library that lets developers describe form fields using a JSON configuration array. Each item specifies _component, _name, and other properties. The library parses the configuration, creates the appropriate zent components, and handles visibility, data fetching, slots, and custom components.

Basic Field Definition

[
  {
    _component: "FormRadioGroupField",
    _name: "sex",
    data: [{text:"男",value:"male"},{text:"女",value:"female"}]
  },
  {
    _component: "FormSelectField",
    _name: "qingjiaType",
    data: [
      {text:"事假",value:"shijia"},
      {text:"年假",value:"nianjia"},
      {text:"调休",value:"tiaoxiu"},
      {text:"病假",value:"bingjia"},
      {text:"产假",value:"chanjia"}
    ]
  },
  {
    _component: "ImageUploader",
    _name: "hospitalMaterial",
    _show: values => ["bingjia","chanjia"].includes(values.qingjiaType),
    tokenUrl: "http://somecdn.youzan.com"
  }
];

The _show function receives the current form values and returns a boolean to control component rendering.

Disabling Children

For consistency, the configuration format forbids the children property; attempting to use it results in an error.

Custom Component Registration

Developers can register their own components via zanForm.register('ComponentName', MyComponent). The component must expose a value prop and support an onChange callback, and it is used inside the configuration with _component.

Slots

When pure configuration cannot meet a requirement, a slot can be declared with _slot. The consuming React component renders a Slot element with a matching id, and the library injects the provided component instance.

Remote Data Fetching

Fields that need options from the server define a _fetch_data function that returns a Promise. The library calls it once and populates the data property. A DecoratorComponent wraps the original field to trigger the fetch in componentDidMount.

Restarting Components

When a field’s options depend on another field (e.g., city list depends on selected province), the configuration can use _subscribe to watch value changes and a restart() call to re‑fetch data and re‑render the dependent field.

Formatting Components

The _format hook receives the component instance and form values, allowing developers to wrap or modify the rendered output, such as adding a unit label after an input.

Form Value Filling

To populate a form with data retrieved from the backend, zanForm.setValues(values, this) recursively calls zentForm.setFieldsValue, eventually stabilizing the form state.

Overall, the article demonstrates how zan‑form’s declarative configuration can simplify the development and maintenance of complex, dynamic forms in React.