# @basenative/forms 中文文档

规范地址：https://npmcn.com/package/%40basenative/forms/

版本：3\.0\.0
npm 元数据更新时间：2026-10-31T13:47:16.559Z
中文译文更新时间：2026-10-31T16:17:42.756Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40basenative/forms
原文对照：https://npmcn.com/package/%40basenative/forms/?lang=original
项目主页：https://github.com/DuganLabs/BaseNative/tree/main/packages/forms#readme
源码仓库：https://github.com/DuganLabs/BaseNative

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

- 包体积（解压后）：23.2 kB，9 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-03-20T05:27:47.674Z
- 最新版本发布：2026-10-31T13:47:16.218Z
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

带有dirty/touch跟踪和模式验证适配器的基于信号的表单状态

## 安装

```sh
npm install @basenative/forms
```

也可以使用：`pnpm add @basenative/forms`、`yarn add @basenative/forms`、`bun add @basenative/forms`

## README

# @ basenative/forms

> 基于信号的表单状态管理，具有验证和字段跟踪功能

部分 [BaseNative](https://github.com/DuganLabs/basenative) 生态系统——基于信号的web运行时，基于原生HTML。

## 安装

```bash
npm install @basenative/forms
```

## 快速入门

```js
import { createForm, createField, required, email, minLength } from '@basenative/forms';

const form = createForm({
  fields: {
    email: createField('', { validators: [required(), email()] }),
    password: createField('', { validators: [required(), minLength(8)] }),
  },
});

// Read field state reactively
import { effect } from '@basenative/runtime';

effect(() => {
  console.log(form.fields.email.value());
  console.log(form.fields.email.errors());
  console.log(form.valid());
});

// Handle submission
form.fields.email.setValue('user@example.com');
form.fields.password.setValue('secret123');

if (form.valid()) {
  const data = form.values();
  await submitToApi(data);
}
```

## API

### `createField(initial, options?)`

创建响应式表单字段。返回：

-   `value` -用当前字段值发出信号。
-   `touched` -信号，字段模糊后为真。
-   `dirty` -信号，值改变后为true。
-   `errors` -带有验证错误消息数组的计算信号。
-   `valid` / `invalid` -计算布尔值。
-   `firstError` -具有第一个错误消息的计算信号或 `null`.
-   `setValue(value)` -更新该值，并将该字段标记为dirty。
-   `touch()` -标记该区域为已触碰。
-   `reset()` -将值、触摸、脏和服务器错误重置为初始状态。
-   `setServerErrors(errors)` -注入服务器端验证错误。

#### 选项

-   `validators` -验证器函数数组（参见下面的内置验证器）。
-   `transform` -在存储之前应用于每个新值的函数。

### `createForm(options)`

从字段映射创建表单组。返回：

-   `fields` -字段图传入。
-   `valid` -计算信号，当所有字段都有效时为true。
-   `values()` -返回当前字段值的纯对象。
-   `reset()` —重置所有字段。
-   `touch()` -将所有字段标记为已触摸。

### `zodAdapter(schema)`

调整一个Zod模式，使其用作表单级验证器。

### 内置验证器

-   `required()` —Value不能为空。
-   `minLength(n)` -字符串必须至少为 `n` 字符。
-   `maxLength(n)` -字符串必须最多为 `n` 字符。
-   `pattern(regex, message?)` -值必须与正则表达式匹配。
-   `email()` -值必须是有效的电子邮件地址。
-   `min(n)` -数值必须至少为 `n`.
-   `max(n)` —数字最多只能为一个 `n`.
-   `custom(fn)` ——运行 `fn(value)` 并使用其返回值作为错误消息 (返回falsy表示有效)。

## 许可证

apache - 2.0

## 常见问题

### @basenative/forms 是什么？

带有dirty/touch跟踪和模式验证适配器的基于信号的表单状态

### 如何安装 @basenative/forms？

在项目目录运行 npm install @basenative/forms，或使用 pnpm add / yarn add / bun add。

### @basenative/forms 支持 TypeScript 吗？

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

### @basenative/forms 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @basenative/forms 可以商用吗？

@basenative/forms 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @basenative/forms 还在维护吗？

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