Vorms 核心 API 全解析：useForm 与 useField 打造响应式表单体验

【免费下载链接】vormsVue Form Validation with Composition API项目地址: https://gitcode.com/gh_mirrors/vo/vorms

Vorms 是一个基于 Vue Composition API 的表单验证库，它提供了简洁而强大的 API，帮助开发者轻松构建响应式表单。本文将深入解析 Vorms 的核心 API——useForm 和 useField，带你快速掌握如何使用它们来创建高效、易用的表单。

快速上手：useForm 基础用法

useForm 是 Vorms 的核心函数，它负责管理整个表单的状态和验证逻辑。通过 useForm，你可以轻松设置初始值、定义验证规则，并处理表单提交。

基本配置

使用 useForm 的第一步是传入配置选项，包括初始值和提交处理函数：

const { register, handleSubmit } = useForm({ initialValues: { name: 'Alex', age: 18, }, onSubmit (values) { console.log({ values }) }, });

这段代码定义了一个包含 name 和 age 字段的表单，并设置了提交处理函数。initialValues 用于设置表单的初始值，onSubmit 则在表单验证通过后被调用。

注册表单字段

有了表单实例后，下一步是注册表单字段。Vorms 提供了 register 方法来完成这个任务：

const { value: name, attrs: nameAttrs } = register('name') const { value: age, attrs: ageAttrs } = register('age')

register 方法返回一个对象，包含 value 和 attrs 属性。value 是一个响应式变量，用于双向绑定表单输入；attrs 则包含了必要的事件处理函数，需要绑定到表单元素上。

深入理解：useForm 高级特性

表单验证

Vorms 提供了灵活的验证机制。你可以在注册字段时指定验证规则：

register('name', { validate: (value) => { if (!value) return '姓名不能为空' if (value.length < 2) return '姓名至少需要2个字符' } })

此外，useForm 还支持在配置选项中设置全局验证函数：

useForm({ // ...其他配置 validate: (values) => { const errors = {} if (values.age < 18) { errors.age = '年龄必须大于等于18岁' } return errors } })

验证时机控制

Vorms 允许你控制验证触发的时机，通过 validateMode 和 reValidateMode 选项：

• validateMode：初始验证模式，默认为 'submit'
• reValidateMode：提交后的验证模式，默认为 'change'

支持的验证模式包括：'blur'、'input'、'change' 和 'submit'。

表单状态管理

useForm 提供了丰富的状态管理方法，包括：

• setValues：设置多个字段的值
• setFieldValue：设置单个字段的值
• setErrors：设置多个错误
• setFieldError：设置单个字段的错误
• resetForm：重置表单到初始状态

精细控制：useField 独立字段管理

除了通过 register 方法注册字段外，Vorms 还提供了 useField 函数，用于更精细地控制单个字段。

基本用法

useField 接收字段名称作为参数，并返回与 register 类似的对象：

const { value: name, attrs: nameAttrs } = useField('name')

独立验证

useField 允许你为单个字段指定验证规则，而无需在 useForm 中集中定义：

const { value: email, attrs: emailAttrs, error } = useField('email', { validate: (value) => { if (!value) return '邮箱不能为空' if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) return '请输入有效的邮箱地址' } })

字段元信息

useField 返回的对象还包含了字段的元信息，如 error、touched 和 dirty：

• error：字段的错误信息
• touched：字段是否被触碰过（即是否失去焦点）
• dirty：字段值是否被修改过

这些元信息可以帮助你构建更丰富的表单交互体验。

实际应用：构建完整表单

结合 useForm 和 useField，我们可以构建一个功能完善的表单：

<template> <form @submit="handleSubmit"> <div> <label>姓名</label> <input v-model="name" v-bind="nameAttrs" /> <span v-if="nameMeta.touched && nameMeta.error">{{ nameMeta.error }}</span> </div> <div> <label>邮箱</label> <input v-model="email" v-bind="emailAttrs" /> <span v-if="emailMeta.touched && emailMeta.error">{{ emailMeta.error }}</span> </div> <button type="submit" :disabled="isSubmitting">提交</button> </form> </template> <script setup> import { useForm, useField } from 'vorms' const { handleSubmit, isSubmitting } = useForm({ initialValues: { name: '', email: '' }, onSubmit(values) { console.log('表单提交:', values) } }) const { value: name, attrs: nameAttrs, ...nameMeta } = useField('name', { validate: value => !value ? '姓名不能为空' : undefined }) const { value: email, attrs: emailAttrs, ...emailMeta } = useField('email', { validate: value => { if (!value) return '邮箱不能为空' if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) return '请输入有效的邮箱地址' } }) </script>

总结

Vorms 的 useForm 和 useField API 为 Vue 开发者提供了强大而灵活的表单管理工具。通过 useForm，你可以轻松管理整个表单的状态和验证逻辑；而 useField 则允许你对单个字段进行精细控制。

无论是简单的登录表单还是复杂的多步骤表单，Vorms 都能帮助你以更少的代码实现更强大的功能。其基于 Composition API 的设计理念，也使得代码更加清晰、可维护。

要深入了解 Vorms 的更多功能，如表单数组处理、自定义验证器等，可以查阅官方文档和源代码。Vorms 的源代码主要位于 packages/core/src/composables/useForm.ts 和 packages/core/src/composables/useField.ts 文件中，你可以通过阅读这些代码来更好地理解其内部工作原理。

开始使用 Vorms，打造你的响应式表单体验吧！

【免费下载链接】vormsVue Form Validation with Composition API项目地址: https://gitcode.com/gh_mirrors/vo/vorms