# Hook Form React

This library is a lightweight, dependency-free solution for form validation and submission designed specifically for React applications.The following component libraries have been adapted: `Next UI`, `Ant Design`, and `MUI`.

该库是一个专为 React 应用设计的轻量级、无依赖的表单验证和提交解决方案。目前已适配完成一下组件库`Next UI`、`Ant Design`、`MUI`。

**推荐直接看示例**：这里更新是最即时的，也是推荐的使用方式。

中文 | [English](https://github.com/luoanb/hook-form-react/blob/main/README.en.md) | [API](https://luoanb.github.io/hook-form-react/) | [GitHub](https://github.com/luoanb/hook-form-react) | [示例:Stackblitz](https://stackblitz.com/~/github.com/luoanb/hook-form-react-example) | [示例:GitHub](https://github.com/luoanb/hook-form-react-example)

基于 React Hooks 和 TypeScript 开发，旨在提供一个简洁、高效且易于扩展的方式来处理表单验证和提交，无论是在简单还是复杂的表单场景中都能灵活应对。本库的设计哲学是兼容性和扩展性，理念是支持开发者以最少的代码实现最丰富的功能，核心不绑定任何 UI 组件库，从而支持所有 React 组件库；对第三方组件库的支持以独立模块方式实现。

## 特点

- **零依赖**：避免了因引入外部依赖而可能导致的项目膨胀和兼容性问题。
- **高度可扩展**：可通过简单配置应对各种验证规则和表单场景，满足不同需求。
- **TypeScript 支持**：充分利用 TypeScript 提供的类型检查，增强代码的可读性和可维护性。
- **通用性**：适配所有 UI 组件库，为 React 开发者提供统一的表单处理解决方案。
- **文档支持**：使用 TypeDoc 生成详尽的文档，帮助开发者更好地理解和使用库中的功能。
- **灵活的打包支持**：使用 Rollup 进行打包，支持 UMD、CommonJS 和 ES 模块格式，以适配不同的使用场景和环境。

## 安装

```shell
# pnpm
pnpm add hook-form-react

# yarn
yarn add hook-form-react

# npm
npm i hook-form-react
```

## 使用

### 基础用法

提供了辅助工具，可以使得开发更快捷，同时不丢失高度的可定制性

```tsx
// 提供了辅助工具，可以使得开发更快捷，同时不丢失高度的可定制性
import { Button, Input } from '@nextui-org/react'
import { useAttr, useFormData, Verifications } from 'hook-form-react'

export const Example = () => {
  const formData = useFormData(
    { password: '', username: '' },
    {
      // 支持多个校验
      password: [
        // 自带验证器必填校验
        // 开发者也可以自行在项目中补充其它验证规则，具体请看开发者文档（待补充）
        Verifications.required()
      ],
      username: [
        // 自带验证器的必填校验 + 自定义提示
        Verifications.required('用户账户不能为空')
      ]
    }
  )

  // 使用组件快速绑定hook
  const attr = useAttr(formData)

  const submit = async () => {
    const isValid = await formData.doAllValidate()
    console.log('submit:isValid: ', isValid)
    if (isValid) {
      console.log('formValue', formData.value)
    }
  }

  return (
    <div className="p-10 pt-18 pb-0 flex-col">
      <Input
        placeholder="请输入账户"
        // 快速绑定
        // NextUI.N_Input属于针对[NextUI.Input]的兼容层
        // 开发者也可以自行在项目中补充第三方组件,具体请看开发者文档(待补充)
        {...attr('username', attr.NextUI.Input)}

        // 自定义绑定逻辑
        // value={formData.value.username}
        // onChange={(e) => formData.pushValue('username', e.target.value)}
        // isInvalid={formData.errors.username?.isInvalid}
        // errorMessage={formData.errors.username?.msg}
      ></Input>
      <Input
        autoComplete="new-password"
        type="password"
        placeholder="请输入登录密码"
        {...attr('password', attr.NextUI.Input)}

        // 自定义绑定逻辑
        // value={formData.value.password}
        // isInvalid={formData.errors.password?.isInvalid}
        // errorMessage={formData.errors.password?.msg}
        // onChange={(e) => formData.pushValue('password', e.target.value)}
      ></Input>

      <Button onClick={submit}>登录</Button>
    </div>
  )
}
```

### 嵌套对象表单

新增一个 hook `useSubFormData`用于处理嵌套表单，原则上可以处理任意层数的对象嵌套（也就是无限套娃）。

```ts
// useSubFormData
const value10Form = useSubFormData(formData.formData, 'value10', {
  haha: [Verifications.required(), Verifications.email()]
})

/**
 * 嵌套对象的表单组件需要用它来绑定
 */
const attrValue10 = useAttr(value10Form)

// 提交
const submit = async () => {
  const isValid = await formData.doAllValidate()
  // 嵌套表单需要单独验证
  const isValidValue10 = await value10Form.doAllValidate()
  console.log('submit:isValid: ', isValid, isValidValue10)
  if (isValid && isValidValue10) {
    //顶层form能拿到所有value
    console.log('formValue', formData.value)
  }
}

// 重置
const reset = () => {
  formData.reset()
  // 错误状态得单独重置
  value10Form.formErrors.reset()
}
```

## 版本说明

- **Next 后续版本计划**

  1. **文档优化**: 后续会提高文档触达性,包括对各个 API 的使用示例, 还有各个组件库在使用过程中的一些细节处理
  2. **稳定性优化**: 优化一些组件库的稳定性, 优化一些组件库的体验
  3. **移动端/小程序组件库支持**: `hook-form-react`模块化且足够轻量(`10k左右`),可满足在小程序中使用, 后续会考虑`Taro`小程序组件库的适配.
  4. **完善开发文档**: 基于可拔插的设计原则, `hook-form-react` 在新增第三方组件库适配、新增自定义验证都是一件简单的事情, 后续将会持续完善开发文档, 以帮助开发者基于项目需求定制的使用`hook-form-react`.

  **V3.0.0**

  1. 重构 API 方法, 名称更简洁和规范 (和以前的不再兼容), 具体以 API 说明为准
  2. 验证自动触发, 目前支持三种验证触发模式: 'change','blur','safeChange'

  ```typescript
  /**
   * 验证触发器
   */
  export enum Trigger {
    /** 变量值更新时触发 */
    'change' = 'change',
    /** 输入框失去焦点触发 */
    'blur' = 'blur',
    /** 安全的变量值更新触发(仅在输入框聚焦时变量变更才会触发) */
    'safeChange' = 'safeChange'
  }
  ```

  3. 验证规则精简, 去除不常用的验证规则.

- **v2.3.0**
  1. **MUI 组件**：完成`MUI`组件库适配, 使用请看 [示例](https://stackblitz.com/~/github.com/luoanb/hook-form-react-example)
- **v2.2.0**

  1. **Antd 组件**：表单组件已经适配完成,(截止到当前版本，我们已经适配完` Next UI`、`Antd `两个组件库), `import { Antd_5 } from 'hook-form-react/Antd_5'`,对于`antd`的适配的所有内容都包含在这里，和核心库隔离。使用示例请参考 [示例:Stackblitz](https://stackblitz.com/~/github.com/luoanb/hook-form-react-example)

- **v2.1.0**

  1. 修复立即赋值,立即验证时,获取不到最新的表单数据的问题(React.useState 异步执行导致的 bug),
     新增两个方法：`doValidateImme` `doAllValidateImme`，当发现使用`doValidate`,`doAllValidate`存在问题时，相应替换一下对应的方法，原则上推荐优先使用`doValidate`,`doAllValidate`。

- **v2.0.2**

  1. 自定义校验规则，`execute?: (value: V, content: any) => Promise<boolean>` ，添加`content`参数用于获取表单上下文数据

- **v2.0.0**

  1. 新增对象嵌套型表单的支持,具体可查看[Stackblitz](https://stackblitz.com/~/github.com/luoanb/hook-form-react-example)
  2. 添加 Stackblitz 示例项目(需要科学上网)

- **v1.0.0**

  1. 重构了验证规则实现类，使用会更友好，同时新增几个常用验证规则 [所有的常用验证规则](https://luoanb.github.io/hook-form-react/classes/Verifications.html)。验证规则并未完全经过测试，有问题欢迎@我。
  2. **NextUI 组件**：目前所有表单已经适配完成 [所有已适配组件](https://luoanb.github.io/hook-form-react/classes/NextUI_2_2.html) (如有遗漏后续会补上，@手动 dog，嘿嘿)
  3. 修复类型声明不准确问题。
  4. 添加测试项目，用于验证功能

- **v0.5.x (底层实现预览)**

  1. 底层框架已实现，使用体验顺畅，可直接[往下看高级用法]()
  2. 整体拓展性良好，组件库相关代码和表单核心代码是完全隔离的，这为今后支持不同的组件库打下基础。
  3. 表单数据状态，表单异常状态完全可控，可以根据业务定制逻辑。
  4. 验证规则也是统一实现，拓展和自定义都很方便。
  5. 零依赖项，纯 hooks。

## 组件库支持情况

- 【90 分】 NextUI 体验良好，且有问题会及时修复（自己也在用）

- 【80 分】 MUI 在 MUI 自己不支持表单验证的前提下，使用 hook-form-react 也是不会错的，至少相对于 react-hook-form，它没有一堆复杂的概念不是吗。

- 【80 分】 Antd 组件自有表单使用体验不错的，优选选自有表单吧，（后续适配主要考虑双组件库情况）。

- 【60 分】 ......

## API 参考

本节应详细介绍库中提供的 Hooks、函数及其参数、返回值类型和使用示例，以便开发者能够快速上手并有效利用库的功能。

[API](https://luoanb.github.io/hook-form-react/)

## 贡献指南

我们欢迎并鼓励社区成员对本项目做出贡献，无论是通过提交错误报告、功能请求还是直接提交代码。请参阅我们的贡献指南了解更多信息。

## 许可证

该项目采用 MIT 许可证，详情请见[LICENSE](./LICENSE)文件。