Vite+TS项目中用Form Builder报formBuilder is not a function错误求助

问题背景 #

此前在React（JS）项目中基于文档实现了Form Builder的自定义字段功能，但将相同代码迁移至Vite+TS项目时，出现Uncaught TypeError: $(...).formBuilder is not a function错误，功能无法正常运行。已尝试配置项目支持JS/JSX，但问题未解决；且若不使用jQuery的.ready()或setTimeout，应用直接崩溃。

相关代码 #

useEffect(() => {
  if (fb.current) {
    setTimeout(() => {
      setFormBuilder(
        $('#form-builder-area').formBuilder({
          ...options,
          fields,
        })
      );
    }, 5000);
  }
}, [fields, options]);

复现步骤 #

• 创建基于最新React、Vite及MUI主题的项目
• 引入Form Builder库并尝试实现动态字段

原因分析与解决方法 #

1. jQuery全局挂载与Form Builder导入顺序问题 #

Form Builder依赖jQuery，但Vite+TS默认不会将jQuery挂载到全局window对象，导致Form Builder无法正确注册到jQuery原型上。

解决步骤：

1. 确保依赖安装完整：

   npm install jquery formBuilder
   

2. 修改vite.config.ts，配置全局jQuery：

   import { defineConfig } from 'vite';
   import react from '@vitejs/plugin-react';
   
   export default defineConfig({
     plugins: [react()],
     resolve: {
       alias: {
         jquery: 'jquery/dist/jquery.min.js'
       }
     },
     define: {
       'window.jQuery': 'jquery',
       'window.$': 'jquery'
     }
   });
   

3. 调整组件内导入顺序，确保Form Builder在jQuery之后导入：

   import React, { useEffect, useRef, useState } from 'react';
   import $ from 'jquery';
   import 'formBuilder/dist/formBuilder.min';
   import 'formBuilder/dist/formBuilder.min.css';
   
   const FormBuilderComponent = () => {
     const fbRef = useRef<HTMLDivElement>(null);
     const [formBuilder, setFormBuilder] = useState<any>(null);
     const options = {}; // 自定义配置项
     const fields = []; // 自定义字段列表
   
     useEffect(() => {
       if (!fbRef.current || formBuilder) return;
   
       // 直接初始化，无需依赖定时器
       const instance = $(fbRef.current).formBuilder({
         ...options,
         fields
       });
       setFormBuilder(instance);
   
       // 组件卸载时清理实例
       return () => {
         instance?.destroy();
       };
     }, [fields, options]);
   
     return <div ref={fbRef}></div>;
   };
   
   export default FormBuilderComponent;
   

2. TypeScript类型声明缺失 #

TS项目中缺少jQuery或Form Builder的类型声明，可能导致类型检查报错或运行时异常。

解决步骤：

1. 安装官方类型声明包：

   npm install @types/jquery --save-dev
   

2. 若formBuilder无官方类型，可在src/vite-env.d.ts中手动添加类型声明：

   declare module 'formBuilder';
   declare global {
     interface JQuery {
       formBuilder(options?: Record<string, any>): any;
     }
   }
   

3. DOM挂载时机问题 #

原代码依赖setTimeout是因为未确保DOM已挂载，改用useRef获取DOM元素可精准控制初始化时机，避免定时器依赖。

关键优化点：

• 使用useRef绑定目标DOM元素，替代全局ID选择器，避免DOM查找冲突
• 在useEffect中判断DOM元素存在后再初始化，无需依赖定时器

内容的提问来源于stack exchange，提问作者Jatan Trivedi