表单 Form

本组件为 React 表单管理提供了一整套支持。通过结合 react-hook-form 和 Radix UI，可以高效构建表单，同时提供动态验证与错误提示。

---

📦 引入方式

import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from '@npmqg/react-ui-form';

---

🧩 使用示例

📚 基本表单

示例

手机号

源码

import { Smartphone } from "lucide-react";
import React from "react";
import { useForm } from "react-hook-form";

import { Button, Input } from "@npmqg/react-ui-core";
import {
  Form,
  FormControl,
  FormField,
  FormItem,
  FormLabel,
  FormMessage,
} from "@npmqg/react-ui-form";

export default function FormIndex() {
  const form = useForm({
    defaultValues: {
      account: "",
    },
    mode: "onChange", // 可以是 'onChange'、'onSubmit' 等
  });

  //表单提交事件
  const onSubmit = (values) => {
    alert("触发提交" + JSON.stringify(values));
  };

  return (
    <Form {...form}>
      <form
        className="space-y-6 flex flex-col h-full w-1/2 bg-section rounded-md p-4"
        onSubmit={form.handleSubmit(onSubmit)}
      >
        <FormField
          control={form.control}
          name="account"
          render={({ field }) => (
            <FormItem>
              <FormLabel>手机号</FormLabel>
              <FormControl>
                <Input
                  maxLength={20}
                  placeholder="请输入手机号"
                  prefix={<Smartphone size={20} />}
                  {...field}
                />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
          rules={{
            required: "请输入手机号",
            pattern: {
              value: /^1\d{10}$/,
              message: "请输入有效的手机号",
            },
          }}
        />

        <Button className="w-full">登录</Button>
      </form>
    </Form>
  );
}

---

📦 组件 API

组件名	描述	主要 Props（类型 - 说明）
Form	封装自 FormProvider，用于提供表单上下文	...formProps：来自 react-hook-form 的属性
FormField	封装 Controller，用于管理单个字段	name (string) - 字段名 control (Control) - 控制器对象 render (function) - 渲染函数
FormLabel	表单字段的标签，自动关联对应控件	htmlFor (string) - 绑定控件 ID className (string) - 样式类
FormControl	结合无障碍属性与错误信息的容器	aria-describedby (string) - 描述信息 ID aria-invalid (boolean) - 是否无效
FormDescription	表单字段的描述信息	className (string) - 自定义样式类
FormMessage	显示表单字段的错误信息	children (ReactNode) - 错误内容 className (string) - 自定义样式类

---

📦 依赖项

• react-hook-form：用于管理表单状态和验证。
• @radix-ui/react-label 和 @radix-ui/react-slot：用于 UI 组件的标签和插槽功能。

---

🧰 使用建议

• 使用 Form 作为表单的根容器，它将为表单提供 react-hook-form 的上下文。
• 使用 FormField 包裹每个表单字段，确保字段的值和验证规则正确传递。
• 使用 FormItem 作为容器，管理表单控件和错误信息的展示。
• 使用 FormLabel、FormControl、FormMessage 等子组件实现表单控件的标签、输入框和错误提示。