在电商供应链中，采购订单是需求与供给之间的法律与经济纽带。其数据结构的复杂性不容小觑：涉及供应商选择、商品清单（含SKU、数量、单价）、金额计算、预计入库时间、结算方式等多个模块。传统表单开发容易陷入混乱：

声明式、集中校验、且具备良好类型提示

以其高性能和简洁的API负责表单状态管理，而 

作为一个功能强大的模式声明与验证库，将为我们定义清晰的数据结构（Schema）并提供运行时校验。两者结合，即使在纯 JS 环境中，也能获得近似 TypeScript 的开发体验和安全性。

用 Zod 定义数据“蓝图”，用 React Hook Form 接管数据“流转”

npm install react-hook-form zod @hookform/resolvers

采购订单表单的数据结构通常分为

。我们首先用 Zod 定义这个结构。

import { z } from 'zod';

// 1. 定义基础、可复用的模式
const positiveInt = z.number().int().positive('必须为正整数');
const nonEmptyString = z.string().min(1, '不能为空');
const futureDate = z.string().refine((val) => new Date(val) > new Date(), {
  message: '预计日期必须是将来的时间',
});

// 2. 定义单个商品行项目
const orderItemSchema = z.object({
  skuId: nonEmptyString,
  skuName: nonEmptyString,
  quantity: positiveInt,
  unitPrice: z.number().positive('单价必须大于0'),
  // 计算字段：通过 `transform` 或后续计算。注意：RHF 不会管理此字段的状态。
  totalPrice: z.number().default(0),
})
// 定义 refine 校验，确保总价 = 数量 * 单价
.refine((data) => data.totalPrice === data.quantity * data.unitPrice, {
  message: '总价计算错误',
  path: ['totalPrice'], // 错误关联到 totalPrice 字段
});

// 3. 定义整个采购订单
export const purchaseOrderSchema = z.object({
  // 表头信息
  orderNumber: z.string().optional(), // 订单号可能由后端生成
  supplierId: nonEmptyString,
  expectedDeliveryDate: futureDate,
  paymentTerms: z.enum(['NET_30', 'NET_60', 'PREPAID']),
  memo: z.string().max(500, '备注不能超过500字').optional(),

  // 核心：商品行项目数组，至少有一项
  items: z.array(orderItemSchema).min(1, '至少需要添加一个商品'),

  // 总计（通常前端计算，这里用 transform 演示，但 RHF 不直接处理 transform 的结果）
  // 更佳实践：在提交时或通过 useEffect 计算
  // grandTotal: z.number().default(0),
});

// 可选：推断出 Schema 对应的数据类型，用于 JSDoc 提示
/**
 * @typedef {z.infer<typeof purchaseOrderSchema>} PurchaseOrderFormData
 */

三、 集成 React Hook Form 与 Zod Resolver

接下来，在表单组件中集成两者。

import React from 'react';
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { purchaseOrderSchema } from '../schemas/purchaseOrderSchema';

const PurchaseOrderForm = ({ initialData, onSubmit, suppliers }) => {
  // 1. 初始化 useForm，连接到 Zod Resolver
  const {
    register,
    handleSubmit,
    formState: { errors, isSubmitting },
    watch,
    setValue,
    getValues,
    control, // 用于 Controller 包裹复杂组件
  } = useForm({
    resolver: zodResolver(purchaseOrderSchema), // 关键集成点
    defaultValues: initialData || {
      supplierId: '',
      expectedDeliveryDate: '',
      paymentTerms: 'NET_30',
      items: [{ skuId: '', skuName: '', quantity: 1, unitPrice: 0, totalPrice: 0 }],
    },
    mode: 'onTouched', // 优化体验：字段被触碰后验证
  });

  // 2. 计算总价的副作用（示例：监听 items 变化）
  React.useEffect(() => {
    const subscription = watch((value, { name }) => {
      // 当 quantity 或 unitPrice 变化时，重新计算对应行的 totalPrice
      if (name && name.startsWith('items') && (name.includes('quantity') || name.includes('unitPrice'))) {
        const match = name.match(/items\.(\d+)\.(quantity|unitPrice)/);
        if (match) {
          const index = parseInt(match[1], 10);
          const items = getValues('items');
          const currentItem = items[index];
          if (currentItem && currentItem.quantity && currentItem.unitPrice) {
            const newTotal = currentItem.quantity * currentItem.unitPrice;
            // 使用 setValue 更新计算字段，并触发重新验证
            setValue(`items.${index}.totalPrice`, newTotal, { shouldValidate: true });
          }
        }
      }
    });
    return () => subscription.unsubscribe();
  }, [watch, setValue, getValues]);

  // 3. 表单提交处理
  const onFormSubmit = async (formData) => {
    // 此时 formData 已经通过 Zod 校验，其格式完全符合 purchaseOrderSchema
    console.log('验证通过的数据:', formData);
    // 可以在这里进行最终的总计计算
    const grandTotal = formData.items.reduce((sum, item) => sum + item.totalPrice, 0);
    const dataToSubmit = { ...formData, grandTotal };
    
    await onSubmit(dataToSubmit); // 调用父组件传入的提交函数
  };

  // 获取当前 items 数组，用于动态渲染
  const items = watch('items', []);

  return (
    <form onSubmit={handleSubmit(onFormSubmit)} className="space-y-6">
      {/* 表头区域 */}
      <div className="card">
        <h3>采购单基本信息</h3>
        <div className="form-row">
          <label>供应商 *</label>
          <select {...register('supplierId')} className={errors.supplierId ? 'error' : ''}>
            <option value="">请选择供应商</option>
            {suppliers.map(sup => (
              <option key={sup.id} value={sup.id}>{sup.name}</option>
            ))}
          </select>
          {errors.supplierId && <span className="error-message">{errors.supplierId.message}</span>}
        </div>
        {/* 其他表头字段：expectedDeliveryDate, paymentTerms 等 */}
      </div>

      {/* 商品行项目动态区域 */}
      <div className="card">
        <h3>采购商品清单</h3>
        {items.map((item, index) => (
          <div key={index} className="item-card">
            <div className="grid grid-cols-4 gap-4">
              <div>
                <label>SKU ID *</label>
                <input
                  {...register(`items.${index}.skuId`)}
                  placeholder="输入SKU或扫码"
                />
                {errors.items?.[index]?.skuId && (
                  <span className="error-message">{errors.items[index].skuId.message}</span>
                )}
              </div>
              {/* 其他字段：skuName, quantity, unitPrice */}
              <div>
                <label>总价</label>
                {/* 总价字段为只读，由前端计算 */}
                <input
                  {...register(`items.${index}.totalPrice`)}
                  readOnly
                  className="readonly"
                />
                {/* 显示 Zod refine 定义的跨字段错误 */}
                {errors.items?.[index]?.totalPrice && (
                  <span className="error-message">{errors.items[index].totalPrice.message}</span>
                )}
              </div>
            </div>
            {/* 删除按钮逻辑 */}
          </div>
        ))}
        {/* 添加商品行的按钮 */}
        <button
          type="button"
          onClick={() => {
            const currentItems = getValues('items');
            setValue('items', [
              ...currentItems,
              { skuId: '', skuName: '', quantity: 1, unitPrice: 0, totalPrice: 0 },
            ]);
          }}
        >
          + 添加商品
        </button>
        {/* 数组级别的错误提示（如 items 为空） */}
        {errors.items && !Array.isArray(errors.items) && (
          <span className="error-message">{errors.items.message}</span>
        )}
      </div>

      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? '提交中...' : '创建采购订单'}
      </button>
    </form>
  );
};

export default PurchaseOrderForm;

（如通过SKU码搜索商品），我们需要使用 RHF 的 

组件，以便将非原生输入控件集成到表单中。

import { Controller } from 'react-hook-form';
import AsyncSelect from 'react-select/async'; // 假设使用 react-select

// 在表单组件内部
<Controller
  name={`items.${index}.skuId`}
  control={control}
  render={({ field }) => (
    <AsyncSelect
      {...field}
      loadOptions={loadSkuOptions} // 你的异步搜索函数
      getOptionLabel={(opt) => opt.name}
      getOptionValue={(opt) => opt.id}
      onChange={(selectedOption) => {
        field.onChange(selectedOption?.id); // 将选中对象的id设为表单值
        // 可以同时自动填充其他字段，如商品名、单价
        if (selectedOption) {
          setValue(`items.${index}.skuName`, selectedOption.name);
          setValue(`items.${index}.unitPrice`, selectedOption.price);
        }
      }}
    />
  )}
/>

：它作为桥梁，将外部组件的值（

将变化通知给 RHF，同时保持对组件样式的完全控制。

下面的流程图概括了从用户输入到最终提交的完整数据流与验证过程：

通过本文的实践，我们成功构建了一个用于电商供应链采购订单创建的

“React Hook Form + Zod”集成模式将数据类型和业务规则置于前端开发的核心位置，极大地提升了供应链这类业务复杂系统的代码质量和开发效率，为后续实现更高级的动态表单引擎（本系列下一篇内容）奠定了坚实的基础。

供应链系统的血脉 | 实现基于 React Hook Form 与 Zod 的强类型采购订单创建表单

前端开发

其他

电商采购订单表单开发实战：使用ReactHookForm和Zod构建强类型表单解决方案。通过Schema-First设计定义数据结构，实现集中校验与高效状态管理，支持动态数组字段和复杂业务规则验证，提升供应链系统开发效率与代码质量。

数据一致性

数据结构

TypeScript

数据流

2026新春采购季

oceanus

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯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编辑器全新改版上线，欢迎大家体验!

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

供应链系统的血脉 | 实现基于 React Hook Form 与 Zod 的强类型采购订单创建表单

供应链系统的血脉 | 实现基于 React Hook Form 与 Zod 的强类型采购订单创建表单

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐