查询表单 SearchForm

SearchForm 是一个基于 react-hook-form 封装的动态搜索表单组件，支持字段配置、国际化、多列响应式布局、外部控制提交与重置等能力，适用于常见列表页搜索场景。

---

📦 引入方式

import { SearchForm } from '@npmqg/react-ui-searchform';

---

🧩 使用示例

📚 基础使用

示例

手机号1

手机号2

手机号3

手机号4

源码

import { useMemo, useRef } from "react";
import { Button, Divider, Input, Space } from "@npmqg/react-ui-core";
import { SearchForm } from "@npmqg/react-ui-searchform";
import {
  FormControl,
  FormField,
  FormItem,
  FormLabel,
  FormMessage,
} from "@npmqg/react-ui-form";

export default function DemoSearchForm() {
  const formRef = useRef();

  const searchList = useMemo(
    () => [
      {
        key: "mobile1",
        value: (
          <FormField
            render={({ field }) => (
              <FormItem>
                <FormLabel>手机号1</FormLabel>
                <FormControl>
                  <Input maxLength={20} placeholder="请输入手机号" {...field} />
                </FormControl>
                <FormMessage />
              </FormItem>
            )}
          />
        ),
        defaultValue: "",
      },
      {
        key: "mobile2",
        value: (
          <FormField
            render={({ field }) => (
              <FormItem>
                <FormLabel>手机号2</FormLabel>
                <FormControl>
                  <Input maxLength={20} placeholder="请输入手机号" {...field} />
                </FormControl>
                <FormMessage />
              </FormItem>
            )}
          />
        ),
        defaultValue: "",
      },
      {
        key: "mobile3",
        value: (
          <FormField
            render={({ field }) => (
              <FormItem>
                <FormLabel>手机号3</FormLabel>
                <FormControl>
                  <Input maxLength={20} placeholder="请输入手机号" {...field} />
                </FormControl>
                <FormMessage />
              </FormItem>
            )}
          />
        ),
        defaultValue: "",
      },
      {
        key: "mobile4",
        value: (
          <FormField
            render={({ field }) => (
              <FormItem>
                <FormLabel>手机号4</FormLabel>
                <FormControl>
                  <Input maxLength={20} placeholder="请输入手机号" {...field} />
                </FormControl>
                <FormMessage />
              </FormItem>
            )}
          />
        ),
        defaultValue: "",
      },
    ],
    []
  );

  return (
    <div>
      <Space>
        <Button onClick={() => formRef.current?.onSubmit()}>搜索</Button>
        <Button onClick={() => formRef.current?.onReset()}>重置</Button>
      </Space>

      <Divider />

      <SearchForm
        ref={formRef}
        searchParamList={searchList}
        defaultValues={{ name: "", role: "" }}
        onSearch={(values) => console.log("搜索条件:" + JSON.stringify(values))}
      />
    </div>
  );
}

---

🧩 Props

属性名	类型	默认值	说明
searchParamList	SearchFormItem[]	[]	表单字段配置数组，每项包含唯一 key 和对应的表单控件 ReactNode
defaultValues	Record<string, any>	{}	表单默认值对象
onSearch	(values: Record<string, any>) => void	()=>{}	表单提交时触发，返回当前字段值对象
noSearch	boolean	false	是否禁用组件挂载时自动执行一次 onSearch

---

🔁 Ref 暴露方法

使用 forwardRef 暴露以下方法，支持父组件远程控制：

{
  searchForm: UseFormReturn;
  onSubmit: () => void;
  onReset: () => void;
}

示例获取方式：

const formRef = useRef();
<SearchForm ref={formRef} ... />

---

🧠 组件特性

📚 国际化支持

所有表单项的 label 会自动通过 Intl.v() 获取当前语言对应的翻译文本。

📚 响应式布局

表单默认 1~5 列响应式布局，自动适配不同屏幕尺寸：

grid-cols-1 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-5

📚 表单组件自动绑定

组件内部自动将 react-hook-form 的 control 和 name 注入到子表单组件中：

React.cloneElement(item.value, {
  name: item.key,
  control: searchForm.control,
});

---

🧾 类型定义说明（简化）

interface ISearchFormProps {
  searchParamList: {
    key: string;
    value: React.ReactElement;
  }[];
  defaultValues?: Record<string, any>;
  onSearch?: (data: Record<string, any>) => void;
  noSearch?: boolean;
}

---

📌 注意事项

• 所有传入的表单子组件必须支持 react-hook-form 的 control 和 name 绑定。
• 如果使用国际化 label，请保证所有组件 label 都通过 props.label 提供。
• 若表单项较复杂（如联动、异步加载），建议自行封装成独立组件再放入 value。