@ burnbuzz/ form- react

反应原始为巴斯福克. 无头组件由TanStack Form提供动力.

安装

pnpm add @buildnbuzz/form-react

同伴依赖性 : @buildnbuzz/form-core, (中文(简体) ), @tanstack/react-form, (中文(简体) ), @tanstack/form-core, (中文(简体) ), react

快速启动

"use client";

import { defineSchema, type InferType } from "@buildnbuzz/form-core";
import { useForm, FieldRenderer } from "@buildnbuzz/form-react";
import { shadcnRegistry } from "@/registry/shadcn/fields";

const schema = defineSchema({
  title: "Contact Form",
  fields: [
    { type: "text", name: "name", label: "Name", required: true },
    { type: "email", name: "email", label: "Email", required: true },
  ],
});

export function ContactForm() {
  const form = useForm({
    schema,
    onSubmit: ({ value }) => {
      console.log(value);
    },
  });

  return (
    <form onSubmit={form.handleSubmit}>
      <FieldRenderer
        field={schema.fields[0]!}
        form={form}
        registry={shadcnRegistry}
      />
      <FieldRenderer
        field={schema.fields[1]!}
        form={form}
        registry={shadcnRegistry}
      />
      <button type="submit">Submit</button>
    </form>
  );
}

核心 API 软件

useForm 钩子

扩展 TanStack 窗体 useForm 带有schema默认,验证,和输出变换的:

import { useForm } from "@buildnbuzz/form-react";

const form = useForm({
  schema,
  defaultValues: { name: "Default" }, // Merges with schema defaults
  contextData: { userRole: "admin" }, // For $context references
  customValidators: {
    /* ... */
  },
  output: { type: "path" }, // Flatten nested output
  onSubmit: ({ value }) => {
    // value is transformed if output config is set
  },
});

<FormProvider>

在全球建立外地登记册:

import { FormProvider } from "@buildnbuzz/form-react";
import { shadcnRegistry } from "@/registry/shadcn/fields";

<FormProvider registry={shadcnRegistry}>
  <App />
</FormProvider>;

<FieldRenderer> 编号 : <RenderFields>

具有注册的 Render 计划字段 :

import { FieldRenderer, RenderFields } from "@buildnbuzz/form-react";

// Single field
<FieldRenderer field={schema.fields[0]!} form={form} />

// All fields
<RenderFields fields={schema.fields} form={form} />

构建自定义字段组件

数据字段

使用 useDataField 在 TanStack 表格中注册的字段 :

import { useDataField } from "@buildnbuzz/form-react";
import type { TextField as TextFieldDef } from "@buildnbuzz/form-core";

export function TextField() {
  const {
    fieldApi,
    field,
    label,
    description,
    errors,
    isInvalid,
    isDisabled,
    isReadOnly,
    isRequired,
    descriptionId,
    errorId,
    ariaDescribedBy,
    handleChange,
    handleBlur,
  } = useDataField<TextFieldDef>();

  return (
    <div>
      <label htmlFor={fieldApi.name}>
        {label}
        {isRequired && <span>*</span>}
      </label>
      <input
        id={fieldApi.name}
        value={fieldApi.state.value ?? ""}
        onChange={(e) => handleChange(e.target.value)}
        onBlur={handleBlur}
        disabled={isDisabled}
        readOnly={isReadOnly}
        aria-invalid={isInvalid}
        aria-describedby={ariaDescribedBy}
      />
      {description && <p>{description}</p>}
      {isInvalid && <p role="alert">{errors.join(", ")}</p>}
    </div>
  );
}

布局字段

使用 useLayoutField 用于容器字段(行,分页,可折叠):

import { useLayoutField } from "@buildnbuzz/form-react";
import type { RowField as RowFieldDef } from "@buildnbuzz/form-core";

export function RowField({ children }: { children?: React.ReactNode }) {
  const { label, description } = useLayoutField<RowFieldDef>();

  return (
    <div className="flex gap-4">
      {label && <label>{label}</label>}
      {description && <p>{description}</p>}
      {children}
    </div>
  );
}

useDataField 返回类型

外地书记官处

将字段类型映射到 React 组件 :

import type { FieldRegistry } from "@buildnbuzz/form-react";

const registry: FieldRegistry = {
  text: TextField,
  email: EmailField,
  select: SelectField,
  group: GroupField,
  array: ArrayField,
  row: RowField,
  tabs: TabsField,
  // ...
};

收到的组件 children 用于嵌入地(组、阵列、行、分页):

export function GroupField({ children }: { children?: React.ReactNode }) {
  const { label, field } = useDataField();

  return (
    <fieldset>
      <legend>{label}</legend>
      {children}
    </fieldset>
  );
}

验证

自动出自 schema + 自定义验证器:

const form = useForm({
  schema,
  customValidators: {
    usernameAvailable: async (value) => {
      const available = await checkUsername(value as string);
      return available ? undefined : "Username taken";
    },
  },
  derivedValidationMode: "blur", // When to run auto-derived checks
});

附加钩

import {
  useFormContext, // Get form instance
  useFieldApi, // Get TanStack field API
  useRegistry, // Get field registry
  useFieldOptions, // Normalize select/radio options
  useNestedErrorCount, // Count errors in child fields
} from "@buildnbuzz/form-react";

资源

• @ burnbuzz/ form- core (中文(简体) ) ——核心原始人
• 种子图案表单 ——底部形式引擎