# @buildnbuzz/form-react 中文文档

规范地址：https://npmcn.com/package/%40buildnbuzz/form-react/

版本：0\.1\.13
npm 元数据更新时间：2026-06-09T19:20:35.772Z
中文译文更新时间：2026-11-08T19:29:00.970Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40buildnbuzz/form-react
原文对照：https://npmcn.com/package/%40buildnbuzz/form-react/?lang=original
项目主页：https://form.buildnbuzz.com/
源码仓库：https://github.com/buildnbuzz/buzzform

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：368 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：react ^18 \|\| ^19
- 首次发布：2026-03-30T22:06:19.342Z
- 最新版本发布：2026-06-09T19:20:35.497Z
- 近 30 天下载量：3288（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

反应原始为巴斯福克.

## 安装

```sh
npm install @buildnbuzz/form-react
```

也可以使用：`pnpm add @buildnbuzz/form-react`、`yarn add @buildnbuzz/form-react`、`bun add @buildnbuzz/form-react`

## README

# @ burnbuzz/ form- react

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

## 安装

```bash
pnpm add @buildnbuzz/form-react
```

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

## 快速启动

```tsx
"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默认,验证,和输出变换的:

```tsx
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>`

在全球建立外地登记册:

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

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

### `<FieldRenderer>` 编号 : `<RenderFields>`

具有注册的 Render 计划字段 :

```tsx
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 表格中注册的字段 :

```tsx
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` 用于容器字段(行,分页,可折叠):

```tsx
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` 返回类型

| 财产 | 说明 |
| --- | --- |
| `fieldApi` | TanStack 实地实例 |
| `field` | 核心外地计划a |
| `form` | 表格实例 |
| `label`, (中文(简体) ), `placeholder`, (中文(简体) ), `description` | 已解析文本( 支持动态值) |
| `isDisabled`, (中文(简体) ), `isReadOnly`, (中文(简体) ), `isRequired`, (中文(简体) ), `isHidden` | 运行时能见度状态 |
| `errors`, (中文(简体) ), `isInvalid`, (中文(简体) ), `errorId`, (中文(简体) ), `descriptionId`, (中文(简体) ), `ariaDescribedBy` | 错误 + a11y 状态 |
| `handleChange`, (中文(简体) ), `handleBlur` | 首选处理器(自动处理、转换) |

## 外地书记官处

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

```ts
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` 用于嵌入地(组、阵列、行、分页):

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

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

## 验证

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

```tsx
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
});
```

## 附加钩

```tsx
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 (中文(简体) )](https://npmcn.com/package/%40buildnbuzz/form-core/README.md) ——核心原始人
-   [种子图案表单](https://tanstack.com/form) ——底部形式引擎

## 常见问题

### @buildnbuzz/form-react 是什么？

反应原始为巴斯福克\.

### 如何安装 @buildnbuzz/form-react？

在项目目录运行 npm install @buildnbuzz/form-react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18 \|\| ^19）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @buildnbuzz/form-react 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @buildnbuzz/form-react 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @buildnbuzz/form-react 可以商用吗？

@buildnbuzz/form-react 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @buildnbuzz/form-react 的下载量有多少？

根据 npm 官方下载统计，@buildnbuzz/form-react 在 2026/10/09 – 2026/11/07 这 30 天内被下载 3,288 次，日均约 110 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @buildnbuzz/form-react 还在维护吗？

最新版本 0\.1\.13 发布于 2026/06/10（4 个月前）；至今共发布 14 个版本，其中过去 12 个月发布了 14 个；首次发布于 2026/03/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。