是供应链的核心环节，我们面临着一个经典的技术挑战：业务流程的

。不同品类的商品入库时，质检标准天差地别：

如果为每一种质检场景都开发一个独立的表单页面，将导致代码库急剧膨胀、维护成本高昂，且无法响应业务的快速变化。本文将带你深入实战，构建一个

基于 JSON 配置的动态表单渲染引擎

，让非技术人员也能通过配置后台，自由定义和调整复杂的入库质检单，实现“一次开发，处处配置”的终极灵活性。

我们的动态表单引擎需要支持以下核心特性：

整个引擎的运作遵循配置驱动（Configuration-Driven）的理念，其架构流程如下：

二、 核心实现：从配置定义到动态渲染 

首先，我们需要用 Zod 定义我们的配置数据结构。这确保了即使配置来自后端，其结构也是可预测且安全的。

import { z } from 'zod';

// --- 基础字段定义 ---
export const FieldTypeEnum = z.enum([
  'text',
  'number',
  'textarea',
  'select',
  'date',
  'checkbox',
  'radio',
  'file',
  'subform', // 子表单（用于数组字段）
]);

// 条件逻辑：定义字段何时显示/启用
const ConditionSchema = z.object({
  field: z.string(), // 依赖的字段路径，如 `basicInfo.category`
  operator: z.enum(['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'contains', 'in']),
  value: z.any(), // 依赖的值
});

// 布局属性
const LayoutSchema = z.object({
  span: z.number().min(1).max(24).optional(), // 栅格占位，假设24栅格
  group: z.string().optional(), // 所属分组
  order: z.number().optional(), // 显示顺序
});

// 单个字段的完整配置
export const FieldConfigSchema = z.object({
  id: z.string(), // 字段唯一标识，如 `expiryDate`
  name: z.string(), // 对应表单数据的路径，如 `inspectionItems.expiryDate`
  label: z.string(), // 显示标签
  type: FieldTypeEnum,
  placeholder: z.string().optional(),
  required: z.boolean().default(false),
  defaultValue: z.any().optional(),
  
  // UI 与交互
  layout: LayoutSchema.optional(),
  disabled: z.boolean().default(false),
  
  // 条件逻辑
  hidden: z.union([z.boolean(), ConditionSchema]).optional(),
  disabledConditions: z.array(ConditionSchema).optional(),
  
  // 特定字段类型配置
  options: z.array(z.object({ label: z.string(), value: z.any() })).optional(), // select/radio
  multiple: z.boolean().default(false).optional(), // 用于 file/select
  children: z.lazy(() => z.array(FieldConfigSchema)).optional(), // 用于 subform 类型的嵌套字段
  
  // 校验规则（Zod原生规则映射）
  validation: z.object({
    min: z.union([z.number(), z.string()]).optional(),
    max: z.union([z.number(), z.string()]).optional(),
    pattern: z.string().optional(), // 正则表达式字符串
    message: z.string().optional(), // 自定义错误信息
  }).optional(),
});

// 表单整体配置
export const FormConfigSchema = z.object({
  id: z.string(),
  version: z.string(),
  title: z.string(),
  description: z.string().optional(),
  fields: z.array(FieldConfigSchema), // 扁平化或嵌套的字段配置
  layout: z.object({
    type: z.enum(['default', 'steps', 'groups']).default('default'),
    groups: z.array(z.object({ id: z.string(), title: z.string() })).optional(),
  }).optional(),
});

/**
 * @typedef {z.infer<typeof FormConfigSchema>} FormConfig
 * @typedef {z.infer<typeof FieldConfigSchema>} FieldConfig
 */

2.2 从配置动态生成 Zod 校验模式 

表单配置本身不包含可执行的校验逻辑。我们需要一个函数，将 

数组转换为 RHF 可用的 Zod Schema。

import { z } from 'zod';

/**
 * 将动态表单配置转换为 Zod Schema
 * @param {FieldConfig[]} fieldConfigs
 * @returns {z.ZodSchema}
 */
export function generateDynamicSchema(fieldConfigs) {
  const schemaShape = {};

  const processFieldConfig = (config) => {
    let fieldSchema;

    // 1. 根据字段类型确定基础 Zod 类型
    switch (config.type) {
      case 'text':
      case 'textarea':
        fieldSchema = z.string();
        break;
      case 'number':
        fieldSchema = z.coerce.number(); // 将输入字符串自动转换为数字
        break;
      case 'date':
        fieldSchema = z.string(); // 或 z.date()，取决于日期选择器返回值
        break;
      case 'checkbox':
        fieldSchema = z.boolean();
        break;
      case 'select':
      case 'radio':
        fieldSchema = z.any();
        if (config.options) {
          const optionValues = config.options.map(opt => opt.value);
          fieldSchema = fieldSchema.refine(val => optionValues.includes(val), {
            message: `请从有效选项中选择`,
          });
        }
        break;
      case 'file':
        // 假设文件上传组件返回 File 对象数组
        fieldSchema = z.instanceof(File).array();
        break;
      case 'subform':
        // 递归处理子字段
        if (config.children) {
          const subSchemaShape = {};
          config.children.forEach(childConfig => {
            subSchemaShape[childConfig.id] = processFieldConfig(childConfig);
          });
          fieldSchema = z.object(subSchemaShape).array(); // 子表单通常是数组
        } else {
          fieldSchema = z.any();
        }
        break;
      default:
        fieldSchema = z.any();
    }

    // 2. 应用必填校验
    if (config.required) {
      fieldSchema = fieldSchema.refine(val => {
        if (val === null || val === undefined) return false;
        if (typeof val === 'string' && val.trim() === '') return false;
        if (Array.isArray(val) && val.length === 0) return false;
        return true;
      }, { message: `${config.label}为必填项` });
    }

    // 3. 应用自定义校验规则
    if (config.validation) {
      const { min, max, pattern, message } = config.validation;
      if (min !== undefined) {
        fieldSchema = fieldSchema.refine(val => val >= min, { message: message || `不能小于${min}` });
      }
      if (max !== undefined) {
        fieldSchema = fieldSchema.refine(val => val <= max, { message: message || `不能大于${max}` });
      }
      if (pattern) {
        const regex = new RegExp(pattern);
        fieldSchema = fieldSchema.refine(val => regex.test(val), { message: message || '格式不正确' });
      }
    }

    return fieldSchema;
  };

  // 构建顶层 Schema Shape
  // 注意：这里进行了简化，假设配置是扁平的。实际需处理嵌套路径。
  // 更复杂的实现需要将 `config.name` (如 ‘inspection.items[0].value’) 解析为嵌套对象。
  // 为简化演示，我们假设配置已预处理为扁平结构。
  fieldConfigs.forEach(config => {
    // 简单实现：使用 id 作为 key，实际应用需处理路径转换
    schemaShape[config.name] = processFieldConfig(config);
  });

  return z.object(schemaShape);
}

2.3 实现动态表单渲染引擎组件 

这是引擎的 UI 核心，它遍历配置，渲染出完整的表单。

import React from 'react';
import { useForm, FormProvider, Controller } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { generateDynamicSchema } from '../utils/generateDynamicSchema';
import { FieldRenderer } from './field-renderers/FieldRenderer';
import { evaluateConditions } from '../utils/conditionLogic';

const DynamicFormEngine = ({ formConfig, onSubmit, defaultValues = {} }) => {
  // 1. 动态生成 Zod Schema
  const dynamicSchema = React.useMemo(() => {
    return generateDynamicSchema(formConfig.fields);
  }, [formConfig]);

  // 2. 初始化 React Hook Form，绑定动态Schema
  const methods = useForm({
    resolver: zodResolver(dynamicSchema),
    defaultValues, // 可用于编辑已有数据
    mode: 'onTouched',
  });

  const { handleSubmit, control, watch, getValues } = methods;

  // 3. 监听所有字段值，用于条件逻辑重算
  const allFormValues = watch();
  const [visibleFields, setVisibleFields] = React.useState(new Set());
  const [disabledFields, setDisabledFields] = React.useState(new Set());

  // 4. 计算条件逻辑的副作用
  React.useEffect(() => {
    const newVisible = new Set();
    const newDisabled = new Set();

    const evaluateField = (fieldConfig) => {
      const isHidden = fieldConfig.hidden;
      const isVisible = isHidden === undefined || 
                       (typeof isHidden === 'boolean' ? !isHidden : !evaluateConditions(isHidden, allFormValues));
      
      if (isVisible) {
        newVisible.add(fieldConfig.id);
      }

      const isDisabled = fieldConfig.disabled || 
                        (fieldConfig.disabledConditions?.some(cond => evaluateConditions(cond, allFormValues)));
      if (isDisabled) {
        newDisabled.add(fieldConfig.id);
      }

      // 递归处理子表单字段
      if (fieldConfig.children) {
        fieldConfig.children.forEach(evaluateField);
      }
    };

    formConfig.fields.forEach(evaluateField);
    setVisibleFields(newVisible);
    setDisabledFields(newDisabled);
  }, [allFormValues, formConfig.fields]); // 当任何表单值变化时重算

  // 5. 递归渲染字段
  const renderField = (fieldConfig) => {
    // 条件渲染判断
    if (!visibleFields.has(fieldConfig.id)) {
      return null;
    }

    const isDisabled = disabledFields.has(fieldConfig.id) || fieldConfig.disabled;

    return (
      <div key={fieldConfig.id} style={{ gridColumn: `span ${fieldConfig.layout?.span || 12}` }}>
        {/* 使用 Controller 将任意UI组件接入 RHF */}
        <Controller
          name={fieldConfig.name}
          control={control}
          render={({ field, fieldState }) => (
            <FieldRenderer
              config={fieldConfig}
              value={field.value}
              onChange={field.onChange}
              onBlur={field.onBlur}
              disabled={isDisabled}
              error={fieldState.error}
            />
          )}
        />
      </div>
    );
  };

  const onFormSubmit = (data) => {
    console.log('动态表单提交数据:', data);
    onSubmit(data);
  };

  return (
    <FormProvider {...methods}>
      <form onSubmit={handleSubmit(onFormSubmit)}>
        <h2>{formConfig.title}</h2>
        {formConfig.description && <p>{formConfig.description}</p>}
        
        {/* 渲染所有根级字段 */}
        <div style={{ display: 'grid', gridTemplateColumns: 'repeat(24, 1fr)', gap: '16px' }}>
          {formConfig.fields.map(renderField)}
        </div>

        <button type="submit">提交质检单</button>
      </form>
    </FormProvider>
  );
};

export default DynamicFormEngine;

以下是表单引擎核心交互与渲染过程的详细序列图：

2.4 实现字段渲染器与条件逻辑 

// components/field-renderers/FieldRenderer.js
import React from 'react';
import TextInput from './TextInput';
import SelectInput from './SelectInput';
import DateInput from './DateInput';
// ... 其他字段类型渲染器

export const FieldRenderer = ({ config, value, onChange, onBlur, disabled, error }) => {
  const commonProps = {
    id: config.id,
    label: config.label,
    value,
    onChange,
    onBlur,
    disabled,
    error: error?.message,
    placeholder: config.placeholder,
    required: config.required,
  };

  switch (config.type) {
    case 'text':
    case 'textarea':
    case 'number':
      return <TextInput {...commonProps} type={config.type} />;
    case 'select':
      return <SelectInput {...commonProps} options={config.options} isMulti={config.multiple} />;
    case 'date':
      return <DateInput {...commonProps} />;
    case 'checkbox':
      return <CheckboxInput {...commonProps} checked={!!value} />;
    case 'subform':
      // 子表单渲染逻辑较为复杂，需递归渲染其 children
      return <SubFormRenderer config={config} value={value || []} onChange={onChange} />;
    // ... 其他类型
    default:
      console.warn(`未知的字段类型: ${config.type}`);
      return null;
  }
};

// utils/conditionLogic.js
export function evaluateConditions(condition, formValues) {
  if (!condition || !condition.field) return false;
  
  const dependentValue = getValueByPath(formValues, condition.field);
  const targetValue = condition.value;

  switch (condition.operator) {
    case 'eq':
      return dependentValue === targetValue;
    case 'neq':
      return dependentValue !== targetValue;
    case 'gt':
      return dependentValue > targetValue;
    case 'gte':
      return dependentValue >= targetValue;
    case 'lt':
      return dependentValue < targetValue;
    case 'lte':
      return dependentValue <= targetValue;
    case 'contains':
      return String(dependentValue).includes(String(targetValue));
    case 'in':
      return Array.isArray(targetValue) ? targetValue.includes(dependentValue) : false;
    default:
      return false;
  }
}

// 工具函数：根据路径字符串（如 'items[0].name'）从对象中获取值
function getValueByPath(obj, path) {
  return path.split('.').reduce((current, key) => {
    const match = key.match(/(\w+)\[(\d+)\]/);
    if (match) {
      return (current && current[match[1]]) ? current[match[1]][match[2]] : undefined;
    }
    return current ? current[key] : undefined;
  }, obj);
}

三、 实战：定义并渲染一个入库质检单 

假设我们需要为“食品类”入库创建一个质检单。其 JSON 配置如下：

// inspectionFoodConfig.js
export const foodInspectionConfig = {
  id: 'inspection-food-v1',
  title: '食品入库质检单',
  fields: [
    {
      id: 'category',
      name: 'basic.category',
      label: '商品大类',
      type: 'select',
      required: true,
      options: [
        { label: '食品', value: 'food' },
        { label: '电子产品', value: 'electronics' },
        { label: '服装', value: 'apparel' }
      ],
      layout: { span: 12 }
    },
    {
      id: 'batchNo',
      name: 'basic.batchNo',
      label: '生产批次号',
      type: 'text',
      required: true,
      layout: { span: 12 }
    },
    {
      id: 'productionDate',
      name: 'inspection.productionDate',
      label: '生产日期',
      type: 'date',
      required: true,
      // 条件显示：仅当商品大类为“食品”时显示
      hidden: {
        field: 'basic.category',
        operator: 'neq',
        value: 'food'
      },
      layout: { span: 12 }
    },
    {
      id: 'expiryDate',
      name: 'inspection.expiryDate',
      label: '保质期至',
      type: 'date',
      required: true,
      hidden: {
        field: 'basic.category',
        operator: 'neq',
        value: 'food'
      },
      layout: { span: 12 }
    },
    {
      id: 'temperatureCheck',
      name: 'inspection.temperatureCheck',
      label: '运输温度记录(℃)',
      type: 'number',
      validation: { min: -20, max: 10, message: '食品运输温度必须在-20℃到10℃之间' },
      hidden: {
        field: 'basic.category',
        operator: 'neq',
        value: 'food'
      },
      layout: { span: 12 }
    },
    {
      id: 'inspectionItems',
      name: 'inspection.items',
      label: '质检明细',
      type: 'subform',
      layout: { span: 24 },
      children: [
        { id: 'itemName', name: 'name', label: '检查项目', type: 'text', required: true },
        { id: 'standard', name: 'standard', label: '标准值', type: 'text' },
        { id: 'actual', name: 'actual', label: '实测值', type: 'text' },
        { id: 'passed', name: 'passed', label: '是否合格', type: 'checkbox' }
      ]
    }
  ]
};

// InspectionPage.js
import DynamicFormEngine from './components/DynamicFormEngine';
import { foodInspectionConfig } from '../configs/inspectionFoodConfig';

const InspectionPage = () => {
  const handleSubmit = async (formData) => {
    // formData 是已经通过动态Schema校验的、结构化的数据
    // 例如: { basic: { category: 'food', batchNo: '...' }, inspection: { ... } }
    console.log('提交质检数据:', formData);
    await api.submitInspection(formData);
  };

  return (
    <div>
      <DynamicFormEngine 
        formConfig={foodInspectionConfig} 
        onSubmit={handleSubmit}
      />
    </div>
  );
};

字段的选择，动态显示或隐藏与食品相关的“生产日期”、“保质期”等字段，并能够动态增删“质检明细”子表单。

通过本文的深入实践，我们成功构建了一个

高度灵活、配置驱动的动态表单渲染引擎

，专门用于应对电商供应链中多变的入库质检场景。让我们回顾核心成果：

通过将易变的部分（UI、规则、流程）抽象为可配置的元数据，将不变的部分（状态管理、校验逻辑、渲染流程）固化为引擎，你构建的系统将获得前所未有的灵活性和可维护性。这不仅是解决入库质检问题的方案，更是构建任何

前端的坚实基石，为后续实现更复杂的供应链流程编排铺平了道路。

仓库收货与质检是供应链的核心环节，我们面临着一个经典的技术挑战：业务流程的高度可变性。不同品类的商品入库时，质检标准天差地别：

供应链系统的血脉 | 构建动态可配的表单渲染引擎，应对多变的入库质检流程

前端开发

架构设计

前端

后端

本文介绍如何构建JSON配置的动态表单引擎，解决电商供应链中多品类商品入库质检的复杂需求。通过声明式配置支持食品、电子、服装等不同品类的质检标准，实现字段动态渲染、条件逻辑和实时校验。采用React Hook Form与Zod集成确保数据安全，提供子表单嵌套和栅格布局功能，满足复杂业务场景需求。

数据结构

数据库

JSON

2026新春采购季

tencentdb-catalog

weda

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

供应链系统的血脉 | 构建动态可配的表单渲染引擎，应对多变的入库质检流程

供应链系统的血脉 | 构建动态可配的表单渲染引擎，应对多变的入库质检流程

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐