zan-admin-form

Schema-driven form designer and renderer for the Zan component ecosystem.

zan-admin-form is intentionally independent from business payloads. It renders JSON form schemas, validates values, handles simple conditional visibility, and builds submit payloads through a declarative map. Business-specific adapters should live in the consuming app.

Install

npm install zan-admin-form

Use

<script setup lang="ts">
import { ref } from 'vue';
import { ZanFormRenderer, type ZanFormSchema } from 'zan-admin-form';
import 'zan-admin-form/style';

const values = ref({});

function handleSubmit(result) {
  // Send result.payload to the business action adapter.
}

const schema: ZanFormSchema = {
  title: 'Batch price update',
  layout: { labelWidth: 96, columns: 24 },
  sections: [
    {
      id: 'main',
      title: 'Price settings',
      fields: [
        {
          field: 'mode',
          label: 'Mode',
          component: 'radio-group',
          span: 24,
          required: true,
          defaultValue: 'fixed',
          options: [
            { label: 'Fixed', value: 'fixed' },
            { label: 'Amount', value: 'amount' },
            { label: 'Percent', value: 'percent' }
          ]
        },
        {
          field: 'direction',
          label: 'Direction',
          component: 'select',
          span: 12,
          visibleWhen: { field: 'mode', in: ['amount', 'percent'] },
          options: [
            { label: 'Increase', value: 'increase' },
            { label: 'Decrease', value: 'decrease' }
          ]
        },
        {
          field: 'value',
          label: 'Value',
          component: 'input-number',
          span: 12,
          required: true,
          props: { min: 0, step: 0.01 }
        }
      ]
    }
  ],
  submit: {
    map: {
      priceMode: '$form.mode',
      direction: '$form.direction',
      value: '$form.value'
    }
  }
};
</script>

<template>
  <ZanFormRenderer v-model="values" :schema="schema" @submit="handleSubmit" />
</template>

Schema Boundary

Supported first batch:

• layout: title, description, sections, tabs, grid columns, label width
• fields: input, textarea, input-number, select, radio-group, checkbox-group, switch, date, time, divider, custom
• runtime: default values, required/min/max/pattern validation, visibleWhen, dynamic child branches, submit payload mapping
• designer: basic schema editing plus raw JSON editing

Business-specific components should be registered through customComponents:

<ZanFormRenderer :schema="schema" :custom-components="{ 'region-picker': RegionPicker }" />

The schema selects component: 'custom' and customType: 'region-picker'; the app owns the component behavior and old payload compatibility.

Dynamic Branches

Options can declare child fields or sections. The renderer activates the matching branch from the current field value, fills child defaults, validates only active children, and removes inactive branch values from submit values.

Dynamic branches are flattened into the same section grid. They are not rendered as an indented tree; parent-child relationships affect visibility and data only.

const schema: ZanFormSchema = {
  sections: [
    {
      fields: [
        {
          field: 'scene',
          label: 'Scene',
          component: 'radio-group',
          defaultValue: 'crowd',
          options: [
            {
              label: 'Crowd',
              value: 'crowd',
              fields: [
                {
                  field: 'crowdType',
                  label: 'Crowd type',
                  component: 'select',
                  defaultValue: 'oldCustomer',
                  options: [
                    { label: 'Old customer', value: 'oldCustomer' },
                    { label: 'New customer', value: 'newCustomer' }
                  ]
                }
              ]
            },
            {
              label: 'Keyword',
              value: 'keyword',
              fields: [
                {
                  field: 'keywordLimit',
                  label: 'Keyword limit',
                  component: 'input-number',
                  defaultValue: 50
                }
              ]
            }
          ]
        }
      ]
    }
  ]
};

Fields can also use children for switch or condition-driven branches:

{
  field: 'smartOptimize',
  label: 'Smart optimize',
  component: 'switch',
  defaultValue: true,
  children: [
    {
      values: [true],
      fields: [
        { field: 'optimizeTarget', label: 'Target', component: 'select' }
      ]
    }
  ]
}