验证

• 声明规则
  • 字符串语法
  • 数组语法
• 显示错误
  • 为整个组设置验证可见性
• 规则提示
  • 防抖 (milli)
  • Alpha
  • 字母数字
  • Alpha-spaces
  • Between
  • Confirm
  • Contains Alpha
  • Contains Alphanumeric
  • 包含字母空格
  • 包含小写字母
  • 包含数字
  • 包含符号
  • 包含大写字母
  • 日期之后
  • 日期之前
  • 日期之间
  • 日期格式
  • 电子邮件
  • 结尾是
  • 是
  • 长度
  • 小写
  • 匹配
  • Max
  • Min
  • Not
  • Number
  • Required
  • Require One
  • Starts With
  • Symbol
  • Uppercase
  • URL
• 自定义规则
  • 定义自定义规则行为
  • 多输入验证规则
  • 全局添加规则
  • 通过属性添加规则
• 自定义消息
  • 验证消息属性
  • 全局验证消息
• 移动验证消息
• 提取消息

FormKit 通过允许您直接在输入项上声明验证规则，使前端验证变得简单。编写自定义规则也很容易，但是有了20多个生产就绪的规则，您很少需要这样做。

声明规则

声明适用于给定输入的验证规则就像提供一个 validation 属性一样简单。规则可以使用两种语法声明：

• 字符串语法
• 数组语法

字符串语法

可以通过指定每个所需规则名称并用管道 | 分隔来声明验证规则。一些规则也可能接受参数，这些参数可以在冒号 : 后提供。您可以通过逗号分隔它们来使用多个参数：

数组语法

验证规则也可以通过提供一个数组来声明。数组的每个元素必须是一个数组，其中第一个元素是验证规则的字符串名称，其余的 n 个元素是该规则的参数。

如果提供的参数需要是实际的 JavaScript 类型，这种方法特别有帮助 — 例如，一个正则表达式（regex）：

显示错误

验证规则始终实时计算 — 这意味着给定字段始终是有效或无效的（在等待异步验证规则运行时被认为是无效的）。然而 — 验证错误的 可见性 是由 validation-visibility 属性决定的。

为整个组设置验证可见性

由于 FormKit 的配置继承，您可以通过使用 config 属性在 form、group 或 list 级别设置 validation-visibility，您仍然可以在每个输入的基础上覆盖它：

规则提示

验证规则根据一些默认特性运行，您可以通过使用“规则提示”在逐个案例的基础上更改这些特性：

• 按顺序运行 - 规则按照声明的顺序运行。当一个规则失败时，任何剩余的规则都不会运行。例如，如果您声明验证规则为 required|length:5，那么在 required 规则通过之前，length 规则不会运行。
• 空值时跳过 - 当输入为空时（在可用规则中，required 规则是唯一的例外），验证规则不会运行。
• 同步 - 所有可用规则都是同步的，不会延迟。
• 阻塞 - 所有验证规则产生阻塞消息，这些消息会阻止表单提交。

上述特性可以在声明规则时通过使用“提示”来修改。规则提示是您添加到规则声明开头的小修饰符字符，用以改变其默认行为：

防抖 (milli)

有时候对验证规则进行防抖是有意义的。要做到这一点，请在您的规则前使用防抖提示 —— 一个包含毫秒数的括号：

Alpha

检查一个值是否仅包含字母字符。有两种字符集：拉丁文和默认。拉丁文字符严格为 [a-zA-Z]，而默认集包括大多数带重音的字符，如 ä、ù 或 ś。

字母数字

检查一个值是否仅由字母字符或数字组成。对于字母部分，你可以传递 default 或 latin - 见上面的 alpha。

Alpha-spaces

检查一个值是否仅由字母字符或空格组成。对于字母部分，你可以传递 default 或 latin - 见上面的 alpha。

Between

检查一个数字是否（包括性地）位于另外两个数字之间。输入值必须是一个数字，否则验证规则将失败。

Confirm

检查一个输入的值是否与另一个输入的值匹配 — 通常用于密码确认。指定要匹配的输入有两种方式：

• 在第二个输入的 name 属性后附加 _confirm。
• 将第一个输入的 name 作为参数传递给第二个输入的确认规则 confirm:name_of_input_1（更具体）。

注意：两个输入必须在同一个 group 或 form 中。

Contains Alpha

检查一个值是否包含字母字符。有两种字符集：拉丁文和默认。拉丁文字符严格为 [a-zA-Z]，而默认集包括大多数带重音的字符，如 ä、ù 或 ś。

Contains Alphanumeric

检查一个值是否包含字母字符或数字。对于字母部分，你可以传递 default 或 latin - 见上面的 contains alpha。

包含字母空格

检查一个值是否包含字母字符或空格。对于字母部分，你可以传递 default 或 latin - 见上面的包含字母。

包含小写字母

检查一个值是否包含小写字母。有两个字符集：拉丁文和默认。拉丁字符严格为 [a-zA-Z]，而默认集包括大多数带重音的字符，如 ä、ù 或 ś。

包含数字

检查一个值是否包含数字。

包含符号

检查一个值是否包含符号。

包含大写字母

检查一个值是否包含大写字母。有两个字符集：拉丁文和默认。拉丁字符严格为 [a-zA-Z]，而默认集包括大多数带重音的字符，如 ä、ù 或 ś。

日期之后

确定一个日期是否在当前日期或作为规则参数提供的日期之后。使用的日期可以是 JavaScript Date 对象或可以由 Date.parse() 解析的字符串。

日期之前

确定一个日期是否在当前日期或作为规则参数提供的日期之前。使用的日期可以是 JavaScript Date 对象或可以由 Date.parse() 解析的字符串。

日期之间

确定一个日期是否在作为规则参数提供的两个日期之间（包括这两个日期）。使用的日期可以是 JavaScript Date 对象或可以由 Date.parse() 解析的字符串。

日期格式

确保输入的日期格式与特定的日期格式相匹配。格式应使用以下格式化标记来指定：

电子邮件

检查输入是否包含有效的电子邮件地址。

结尾是

检查输入的值是否以给定的子字符串结尾。

是

检查输入的值是否至少与提供的一个参数匹配。

长度

检查输入的值是否超过给定的长度，或者在两个长度值之间。它用于验证数组（如列表）、对象（如组）或字符串长度。也可以用来模拟原生的 maxlength 和 minlength。

小写

检查一个值是否只包含小写字符。有两个字符集：拉丁和默认。拉丁字符严格为 [a-zA-Z]，而默认集包括大多数带重音的字符，如 ä、ù 或 ś。

匹配

检查输入是否与特定的值或模式匹配。如果你传递多个参数，它会检查每一个直到找到匹配项。

在验证属性中传递字符串进行简单匹配时，你可以用斜杠 / 模板化你的参数，以传入你自己的正则表达式。

当使用字符串字符串语法时，你不能转义用于定义验证规则本身的字符 (|,:)。要在你的正则表达式中使用这些字符，你必须使用替代的数组语法。

Max

检查一个Number是否小于或等于最大值。默认的最大值是10。

您也可以使用这个规则来验证一个Array的长度是否小于或等于最大值。

Min

检查一个Number是否大于或等于最小值。默认的最小值是1。

您也可以使用这个规则来验证一个Array的长度是否大于或等于最小值。

Not

检查输入数据是否不匹配一组预定义的值。

Number

检查输入是否为isNaN()评估的有效数字。

Required

检查输入是否为空。

如果您不希望空白字符使required规则通过，您可以将trim作为参数传递给规则：

Require One

检查多个输入，如果其中任何一个有值，则通过。

注意：两个输入必须在同一个group或form中。

Starts With

检查输入是否以提供的选项之一开头。

Symbol

检查一个值是否只包含符号。

Uppercase

检查一个值是否只包含大写字符。有两个字符集：拉丁字符和默认字符集。拉丁字符严格为[a-zA-Z]，而默认字符集包括大多数带重音的字符，如ä、ù或ś。

URL

检查输入值是否看起来是一个格式正确的URL，包括协议。这不检查URL是否实际解析。

自定义规则

验证规则是接受核心节点并返回布尔值的函数 — true 表示通过，false 表示失败。此外，传递给验证规则的任何参数都作为参数 1-n 可用。编写自己的规则很简单 — 例如：

/**
 * 文件: my-custom-rules/monday.js
 *
 * 一个人为的验证规则，确保输入的值是 monday 或 mon。
 */
const monday = function (node) {
  return node.value === 'monday' || node.value === 'mon'
}

export default monday

定义自定义规则行为

如验证规则提示部分所述，验证规则 — 包括您的自定义规则 — 按照默认行为操作：它们按顺序运行，当输入的值为空时会被跳过，是同步的，并且是阻塞的。如果您希望您的规则的默认操作不同，您可以覆盖这些在您的自定义验证规则上：

/**
 * 一个人为的验证规则，确保输入的值是 monday 或 mon。
 */
const monday = function (node) {
  return node.value === 'monday' || node.value === 'mon'
}

// 覆盖您的自定义规则的默认规则行为
monday.blocking = false
monday.skipEmpty = false
monday.debounce = 20 // 毫秒
monday.force = true

export default monday

您也可以通过规则提示在特定情况下覆盖这些行为。

一旦您编写了一个验证函数 — 您需要在 FormKit 中注册验证规则 — 无论是全局还是特定于某个输入。

多输入验证规则

验证规则可以依赖于您的表单树中其他输入的值。为此，请使用节点遍历来定位另一个节点并访问其值：

全局添加规则

要在您的项目中任何地方使用验证规则，您可以在注册 Vue 的 FormKit 插件的任何地方指定它。

import { createApp } from 'vue'
import App from './App.vue'
import { plugin, defaultConfig } from '@formkit/vue'
import monday from './my-custom-rules/monday'

// prettier-ignore
createApp(App).use(plugin, defaultConfig({
  rules: { monday },
})).mount('#app')

安装后，您可以在项目中的任何地方使用您的验证规则。

<FormKit validation="required|monday" />

要自定义当您的自定义验证失败时显示的错误消息，请按照此处的说明操作。

通过属性添加规则

要为特定输入添加验证，请使用 validation-rules 属性。

自定义消息

有几种方法可以自定义验证消息。最基本的方法是使用 validation-label 属性 — 允许您更改字段在预定义验证消息中的名称。

如果您需要更具体，您有两个选择：

• 使用属性覆盖规则的消息。
• 全局覆盖验证规则的消息。

验证消息属性

您可以通过在 FormKit 输入上提供一个字符串或函数的对象，直接覆盖验证消息。

使用字符串

要在单个 FormKit 输入上覆盖验证消息，请添加 validation-messages 属性，并带有规则名称和相应消息的对象。

使用函数

如果您需要为验证规则提供更多能力，您可以使用函数而不是字符串。该函数会传递一个上下文对象。

验证消息上下文对象：

让我们使用函数而不是字符串来重写上面的例子，以便对 validation-messages 属性有更多的控制：

全局验证消息

如果您想要覆盖（或添加）整个项目中的验证规则消息，您可以在注册 FormKit 时，定义这些消息规则，并放在您想要覆盖的语言键下：

import { createApp } from 'vue'
import App from './App.vue'
import { plugin, defaultConfig } from '@formkit/vue'
import monday from './my-custom-rules/monday'

// prettier-ignore
createApp(App).use(plugin, defaultConfig({
  messages: {
    en: {
      validation: {
        required({ name }) {
          return `请填写${name}字段。`
        }
      }
    }
  }
})).mount('#app')

移动验证消息

如果您希望在 <FormKit /> 组件之外渲染输入的验证消息，您可以利用 <FormKitMessages /> 组件，并将输入的节点作为属性传递。使用这个组件会禁用消息的默认显示（位于输入下方），并将它们移动到 <FormKitMessages /> 组件所在的位置：

提取消息

要从 输入的核心节点 获取所有验证消息，您可以使用从 @formkit/validation 导出的 getValidationMessages 函数。这个函数会递归检查给定节点及其所有子节点的验证消息，并返回一个将核心节点映射到验证消息的 Map，这使它非常适合与表单一起使用：