@chantouchsek/validatorjs

中文文档

2.3.0发布于 2026/10/17MITTypeScriptESM + CJS近 30 天下载 2891

校验器.js库使得JavaScript中的数据验证在浏览器和Node.js中都非常容易.

文档目录22 节

为什么使用验证器Js?
安装
使用 pnpm
使用 npm
使用线条
基本用途
有时需要和存在的可选字段
嵌入式规则
WildCards规则
所需有条件规则和比较
现行规则
可选电话验证
注册自定义验证规则
同步验证
与有效输入合作
错误消息
自定义错误消息
自定义属性名称
语言支持
发展
许可证
贷项

验证器Js

校验器Js库使得JavaScript中的数据校验在浏览器和Node.js中都非常容易. 这个图书馆是从验证器Js 以打字符重写以添加更多规则和特性.

为什么使用验证器Js?

在浏览器和节点都工作.
可读和可申报审定规则.
有多语种支持的错误消息 .
CommonJS/浏览支持.
ES6支持.
重写为打字符

安装

使用 pnpm

pnpm add @chantouchsek/validatorjs

使用 npm

npm install @chantouchsek/validatorjs

使用线条

yarn add @chantouchsek/validatorjs

基本用途

import { Validator } from '@chantouchsek/validatorjs'

const data = { email: '[email protected]' }
const rules = { email: 'required|email' }
const options = { customAttributes: { email: 'Email address' } }
const validation = new Validator(data, rules, options)
validation.passes() // => true

数据 {对象} - 您想要验证的数据

规则 {对象} - 验证规则

选项 {Object} - 可选验证和信件配置

选项
- 语言?: LangTypes 选择捆绑的语言
- 确认反向 ? : boolean QQ 可选显示确认字段的错误消息而不是密码
- 自定义消息 ?: 记录 < string, any > QQ 可选自定义错误消息以返回
- 自定义属性 ?: 记录 <string, any > QQ 可选自定义属性名称以返回
- 默认属性Name : 部分 < 记录 < LangTypes, string * * * * * 替换: 选定地块的属性

下面的例子使用 TypeScript 和软件包的名称 Validator 输出。同步 passes() 财务报告和审定财务报表 fails() 返回布尔; 基于召回的验证返回 void。。。 . passesAsync() 总是返回 Promise<boolean> 无论是哪种规则. 每次验证运行都会取代实例之前的错误和错误计数.

例1 - 通过验证

import { Validator } from '@chantouchsek/validatorjs'

const data = {
  age: 28,
  email: '[email protected]',
  name: 'John',
}

const rules = {
  age: 'min:18',
  email: 'required|email',
  name: 'required',
}

const validation = new Validator(data, rules)

validation.passes() // => true
validation.fails() // => false

将审定规则适用于数据对象,使用相同的对象密钥名称规则对象.

例2 - 未能验证

import { Validator } from '@chantouchsek/validatorjs'

const validation = new Validator(
  {
    email: 'not an email address.com',
    name: 'D',
  },
  {
    email: 'required|email',
    name: 'size:3',
  },
)

validation.fails() // => true
validation.passes() // => false

// Error messages
validation.errors.first('email') // => 'The email format is invalid.'
validation.errors.get('email') // => ['The email format is invalid.']
validation.errors.has('name') // => true
validation.errorCount // => 2
validation.errors.all() // => { email: ['The email format is invalid.'], name: ['The name must be 3 characters.'] }

例3 - 有默认属性名称

import { Validator } from '@chantouchsek/validatorjs'

const validation = new Validator(
  {
    email: 'not an email address.com',
    name: 'D',
  },
  {
    email: 'required|email',
    name: 'size:3',
  },
  {
    locale: 'ja',
    defaultAttributeName: {
      en: '',
      ja: 'この項目',
    },
  },
)

validation.fails() // => true
validation.passes() // => false

// Error messages
validation.errors.first('email') // => 'この項目は正しいメールアドレスを入力してください。'

有时需要和存在的可选字段

例如: email 跳过缺失, undefined, (中文(简体) ), null空字符串数值。添加 required 拒绝他们. sometimes 仅当缺少密钥; 明确提供的空值仍在运行 required。。。 . present 目前拒绝丢失的密钥和 undefined,但接受 null, (中文(简体) ), 空字符串,零,假,和空数组.

import { Validator } from '@chantouchsek/validatorjs'

new Validator({}, { email: 'email' }).passes() // => true
new Validator({ email: '' }, { email: 'email' }).passes() // => true
new Validator({}, { email: 'required|email' }).passes() // => false
new Validator({}, { email: 'sometimes|required|email' }).passes() // => true
new Validator({ email: '' }, { email: 'sometimes|required|email' }).passes() // => false
new Validator({ email: undefined }, { email: 'sometimes|required' }).passes() // => false
new Validator({ email: null }, { email: 'present' }).passes() // => true
new Validator({ email: undefined }, { email: 'present' }).passes() // => false
new Validator({}, { email: 'present' }).passes() // => false
new Validator({ count: 0, enabled: false }, { count: 'required', enabled: 'required' }).passes() // => true
new Validator({ tags: [] }, { tags: 'required|array' }).passes() // => false

required 检查非空白字符串的表示式, 所以零和假的通过空数组失败。纵使空出,阵列仍然运行普通规则. 校验不会强制输入类型:一个数字字符串可以通过 numeric 时在返回的数据中保留字符串.

嵌入式规则

嵌入式物体也可以被验证. 有两种方式来宣布嵌入物的验证规则. 第一个办法即以相应的嵌入式物体结构声明验证规则,以反映数据。第二条路以平分键名宣布验证规则。例如,验证下列数据:

import { Validator } from '@chantouchsek/validatorjs'

const data = {
  bio: {
    age: 28,
    education: {
      primary: 'Elementary School',
      secondary: 'Secondary School',
    },
  },
  name: 'John',
}
// Either nested rules or flattened paths can validate this data.
const nested = {
  bio: {
    age: 'min:18',
    education: {
      primary: 'string',
      secondary: 'string',
    },
  },
  name: 'required',
}

// OR

const flattened = {
  'bio.age': 'min:18',
  'bio.education.primary': 'string',
  'bio.education.secondary': 'string',
  'name': 'required',
}

new Validator(data, nested).passes() // => true
new Validator(data, flattened).passes() // => true

WildCards规则

WildCards也可以被验证.

import { Validator } from '@chantouchsek/validatorjs'

const data = {
  users: [
    {
      bio: {
        age: 28,
        education: {
          primary: 'Elementary School',
          secondary: 'Secondary School',
        },
      },
      name: 'John',
    },
  ],
}
const rules = {
  'users': 'required|array',
  'users.*.bio.age': 'min:18',
  'users.*.bio.education.primary': 'string',
  'users.*.bio.education.secondary': 'string',
  'users.*.name': 'required',
}

new Validator(data, rules).passes() // => true

const invalid = new Validator({ users: [{ name: '' }] }, { 'users.*.name': 'required' })
invalid.fails() // => true
invalid.errors.first('users.0.name') // => 'The users 0 name field is required.'

使用父数组的规则要求至少一个项目:通配符规则没有用于验证缺失或空数组的条目。通配符扩展时校验符被构建; 如果数组结构发生变化, 创建一个新实例.

所需有条件规则和比较

字符串-形式比较参数为字符串. 阵列形式参数保存在比较布尔或数字时使用它们.

import { Validator } from '@chantouchsek/validatorjs'

const input = {
  account: { kind: 'business' },
  company: '',
  password: 'secret123',
  password_confirmation: 'secret123',
  email: '[email protected]',
  emailAgain: '[email protected]',
  backupEmail: '[email protected]',
}
const rules = {
  company: 'required_if:account.kind,business',
  password: 'required|confirmed',
  emailAgain: 'required|same:email',
  backupEmail: 'required|different:email',
}
const validation = new Validator(input, rules)
validation.fails() // => true
validation.errors.has('company') // => true
validation.errorCount // => 1

new Validator({ enabled: false }, { reason: [{ required_if: ['enabled', false] }] }).passes() // => false
new Validator({ status: 'draft' }, { title: 'required_unless:status,draft' }).passes() // => true
new Validator({ email: '[email protected]' }, { name: 'required_with:email' }).passes() // => false
new Validator({ email: '[email protected]' }, { name: 'required_without:email' }).passes() // => true
new Validator({ first: 'Ada', last: 'Lovelace' }, { name: 'required_with_all:first,last' }).passes() // => false
new Validator({ first: 'Ada' }, { name: 'required_without_all:first,last' }).passes() // => true

const users = { users: [{ needsPhone: true, phone: '' }, { needsPhone: false }] }
const userRules = { 'users.*.phone': [{ required_if: ['users.*.needsPhone', true] }] }
const perUser = new Validator(users, userRules)
perUser.fails() // => true
Object.keys(perUser.errors.all()) // => ['users.0.phone']

same 财务报告和审定财务报表 different 使用严格的平等。当前限制:比较路径通过数组不能正确解决这两个规则,以及 confirmed 寻找一个顶级确认域。有或无有条件规则的使用真理,所以零和虚实的计算为缺席. 虽然他们的规则名称如下文档多字段, required_with 财务报告和审定财务报表 required_without 目前解决只有一个路径; 在列表处理固定之前使用单一的依赖性 .

现行规则

验证规则没有隐含的"要求". 如果一个字段是 未定义 或空弦会过去审定。如果您想要对未定义或“ ” 的验证失败, 请使用 所需经费 规则.

已接受

被验证的字段必须是"是","在","1"或"真实". 这对验证"服务条款"的接受很有用.

日期之后

被验证的字段必须在命名的顶级输入字段的日期后.

等:日期之后

被验证的字段必须在命名的顶级输入字段之后或等同日期.

阿尔法

正在验证的字段必须是完全字母化的字符.

阿尔法达什

被验证的字段可能有字母数字字符,以及破折号和下划线.

α num

被验证的字段必须是完全字母化的字符.

数组

正在验证的字段必须是数组 .

日期:

被验证的字段必须在命名的顶级输入字段的日期之前.

前为平:日期

被验证的字段必须在命名的顶级输入字段之前或等同日期.

在: min, 最大值之间

正在验证的字段必须在给定分和最大分之间有大小。字符串、数字和数组在和大小规则一样时尚.

布尔

正在验证的字段必须是窗体的布尔值 true, (中文(简体) ), false, (中文(简体) ), 0, (中文(简体) ), 1, (中文(简体) ), 'true', (中文(简体) ), 'false', (中文(简体) ), '0' , (中文(简体) ), '1', (中文(简体) ),

确认

正在验证的字段必须有相匹配的 foo 确认域。例如,如果验证中的字段是密码,输入中必须包含匹配的密码确认字段.

日期

正在验证的字段必须是Javascript中可接受的有效日期格式 Date 对象.

数字:值

被验证的字段必须是数字并必须有准确的值长度.

数字在: min, max之间

目前的执行情况检查,数字值介于分钟和最大之间; 它不检查数字计数, 尽管规则的名称和错误消息.

不同属性

给定的字段必须与被验证的字段不同.

电子邮件

验证中的字段必须被格式化为电子邮件地址.

六进制

正在验证的字段应该是十六进制格式. 与其他规则结合有用 hex|size:6 页:1 六分色码验证.

在: foo, bar, 中, 中, 中.

验证中的字段必须包含在给定的数值列表中. 字段可以是数组或字符串.

整数

正在验证的字段必须具有整数值 .

最大值:值

验证属性不大于给定大小

注:最大检查包含在内.

例1 - 最大验证

import { Validator } from '@chantouchsek/validatorjs'

const rules = {
  phone: 'required|digits:11|max:11',
}
const input = {
  phone: '01234567890',
}
new Validator(input, rules).passes() // => true

例2 - 最大验证

import { Validator } from '@chantouchsek/validatorjs'

const rules = {
  phone: 'integer|max:16',
}
const input = {
  phone: '18',
}
new Validator(input, rules).passes() // => false

分:值

验证属性至少是一个给定大小 .

注:最低限度检查是包容性的.

例1 - 最小验证

import { Validator } from '@chantouchsek/validatorjs'

const rules = {
  phone: 'required|digits:11|min:11',
}
const input = {
  phone: '01234567890',
}
new Validator(input, rules).passes() // => true

例2 - 最小验证

import { Validator } from '@chantouchsek/validatorjs'

const rules = {
  phone: 'integer|min:11',
}
const input = {
  phone: '18',
}
new Validator(input, rules).passes() // => true

不是在: foo, bar, , , , ,...

验证中的字段不得包含在给定的数值列表中.

数字

验证属性为数值。一个数字的字符串表示会通过.

import { Validator } from '@chantouchsek/validatorjs'

const rules = {
  amount: 'numeric|digits:5',
}
new Validator({ amount: '12345' }, rules).passes() // => true

当前

正在验证的字段必须具有除 undefined,但可以是空的.

所需经费

拒绝 null 财务报告和审定财务报表 undefined,然后检查字符串表示式包含至少有一个非空白字符。 0和假通;空数组失败.

需要 if: aother field, 值

如果另一个字段严格等于所提供的值,则正在验证的字段必须是非空的.

需要( u),除非:另一个字段,值

正在验证的字段必须是非空的,除非其他字段严格等于所提供的值.

需要 with: foo, bar,...

正在验证的字段必须存在,而不能仅在其他指定字段中存在时才为空.

需要 with all:foo, bar,...

正在验证的字段必须存在,而不能只在所有其他指定字段都存在的情况下才为空.

需要没有: foo, bar,...

正在验证的字段必须存在,而不能仅在其他指定字段不存在时才为空.

需要无 all: foo, bar,...

正在验证的字段必须存在,而不能只在所有其他指定字段不存在时才为空.

有时

在某些情况下,您可能只希望对正在验证的数据中存在的字段进行验证检查。为了迅速完成这项工作,在规则列表中加入有时的规则:

import { Validator } from '@chantouchsek/validatorjs'

const rules = {
  email: 'sometimes|required|email',
}
new Validator({}, rules).passes() // => true
new Validator({ email: '' }, rules).passes() // => false

在上述例子中,电子邮件字段只有在输入中存在时才会被验证.

相同:属性

给定的字段必须匹配被验证的字段.

大小:值

正在验证的字段必须有匹配给定值的大小。对于字符串数据,数值对应数字字符的输入。对于数值数据,值对应给定的整数值.

字符串

正在验证的字段必须是字符串 .

url 密码

验证属性是否具有有效的 URL 格式

regex: 扩展

正在验证的字段必须匹配给定正则表达式 .

说明: 当使用 regex 模式,也许有必要在一个阵列中指定规则,而不是使用管分隔符,特别是正则表达式包含管字符时. 你用过的每把后斜刀你们的regex图案你们必须用另一个后向斜线来逃避对方.

例3 - Regex 验证

import { Validator } from '@chantouchsek/validatorjs'

const validation = new Validator(
  {
    name: 'Doe',
    salary: '10,000.00',
    yearOfBirth: '1980',
  },
  {
    name: 'required|size:3',
    salary: ['required', 'regex:/^(?!0\\.00)\\d{1,3}(,\\d{3})*(\\.\\d\\d)?$/'],
    yearOfBirth: ['required', 'regex:/^(19|20)[\\d]{2,2}$/'],
  },
)

validation.fails() // => false
validation.passes() // => true

例4 - 类型检查验证

import { Validator } from '@chantouchsek/validatorjs'

const validation = new Validator(
  {
    age: 30,
    name: '',
  },
  {
    age: ['required', { in: [29, 30] }],
    name: [{ required_if: ['age', 30] }],
  },
)

validation.fails() // => true
validation.passes() // => false

可选电话验证

电话验证是一种选入适配器. 明确安装其可选端点 :

pnpm add @chantouchsek/validatorjs libphonenumber-js
# Or: npm install @chantouchsek/validatorjs libphonenumber-js
# Or: yarn add @chantouchsek/validatorjs libphonenumber-js

导入核心软件包时不装入电话解析器或元数据。分开 /phone 输入负载 libphonenumber-js/max (完整的元数据),但没有登记直到你打电话 registerPhoneRule(Validator)。只使用核心的用户不需要对等器; 导入 /phone 不产生模块解析错误。无害环境管理和共同JS 支持进口,同时对两个条目进行TypeScript声明.

import { Validator } from '@chantouchsek/validatorjs'
import { registerPhoneRule } from '@chantouchsek/validatorjs/phone'

registerPhoneRule(Validator)

const international = new Validator({ contact: '+855 12 345 678' }, { contact: 'required|phone' })
international.passes() // => true

const national = new Validator({ contact: '012 345 678' }, { contact: 'phone:KH' })
national.passes() // => true

const missingCountry = new Validator({ contact: '012 345 678' }, { contact: 'phone' })
missingCountry.fails() // => true

const foreignCountry = new Validator({ contact: '+1 213 373 4253' }, { contact: 'phone:KH' })
foreignCountry.fails() // => true

phone 需要从 +。。。 . phone:KH 接受一个国家编号或国际编号:柬埔寨。其他大写国家由 libphone number-js 支持的代码以同样的方式工作(US, (中文(简体) ), CA, (中文(简体) ), GB, (中文(简体) ), FR, (中文(简体) ), ,包括其支持的区域代码)。解析的国家必须匹配, 包括共享呼叫码的国家。国别拨号前缀遵循解析器的国家规则. UK,小写代码,不支持代码,为空 phone:,国家清单,非字符串国家参数在评价时失败. 没有登记或格式化的选择;只使用一条规则或一个国家.

当整个输入解析为有效号码。绕行道,扩展道(ext., (中文(简体) ), x),以及 tel: URIs为拒绝。只接受原始字符串; 数字输入会丢失正 0 绝不能使用。编号计划的有效性没有证明任务, 所有权、可达到性或短信能力。保持可选对等电流,因为它的元数据决定了有效性.

空值遵循现有的非隐规则行为 :

import { Validator } from '@chantouchsek/validatorjs'
import { registerPhoneRule } from '@chantouchsek/validatorjs/phone'

registerPhoneRule(Validator)
new Validator({}, { contact: 'phone' }).passes() // => true
new Validator({ contact: null }, { contact: 'phone' }).passes() // => true
new Validator({ contact: '' }, { contact: 'required|phone' }).fails() // => true
new Validator({}, { contact: 'sometimes|required|phone' }).passes() // => true
new Validator({ contact: '' }, { contact: 'sometimes|required|phone' }).fails() // => true
new Validator({ contact: [] }, { contact: 'phone' }).fails() // => true

缺少、未定义、无效、空和仅空白值跳过 phone; 添加 required 需要一个值。对阵列进行评估并否决. present, (中文(简体) ), nullable,而有条件的规则保留其现有的语义. 跳过可选值的无效的国家选项不是飞行前错误 .

嵌入字段、通配符规则、信件和属性名称使用现有的 API :

import { Validator } from '@chantouchsek/validatorjs'
import { registerPhoneRule } from '@chantouchsek/validatorjs/phone'

registerPhoneRule(Validator)
const input = { contacts: [{ number: 'bad' }, { number: '+855 12 345 678' }] }
const validation = new Validator(input, { 'contacts.*.number': 'required|phone:KH' }, {
  customMessages: { 'phone.contacts.*.number': 'Enter a valid phone number for :attribute.' },
  customAttributes: { 'contacts.*.number': 'contact number' },
})
validation.fails() // => true
validation.errors.first('contacts.0.number') // => 'Enter a valid phone number for contact number.'

const valid = new Validator({ contact: '  +855 12 345 678  ' }, { contact: 'phone' })
valid.validated() // => { contact: '  +855 12 345 678  ' }

验证从不格式化或变异输入; validated() 保留所提供的绳子。登记可以重复,并明确取代现有的同步 phone 规则。为适配器保留规定名称.

电话留言使用当地人 phone 模板当存在时,然后其已存在的常规 def 倒计时(英语: The contact attribute has errors.) (中文(简体) ). 实例自定义消息为正常优先。提供本地化电话文本 :

import { Validator } from '@chantouchsek/validatorjs'
import { registerPhoneRule } from '@chantouchsek/validatorjs/phone'

const previousLocale = Validator.getDefaultLang()
const original = Validator.getMessages('fr')
Validator.setMessages('fr', { ...original, phone: 'Le numéro :attribute est invalide.' })
Validator.useLang('fr')
registerPhoneRule(Validator) // Preserves this translation and the default locale.

const validation = new Validator({ contact: 'bad' }, { contact: 'phone' }, { locale: 'fr' })
validation.fails() // => true
validation.errors.first('contact') // => 'Le numéro contact est invalide.'

Validator.setMessages('fr', original)
Validator.useLang(previousLocale)

可选适配器只对导入的应用程序添加 parser/ full-metadata 成本 /phone;对等点仍然属于此软件包构建的外部. 现有核心出口、文件验证行为和消费者节点要求保持不变.

注册自定义验证规则

使用 Validator.register(name, callbackFn, errorMessage?)。。。 .

名称 - 规则的名称.

回调Fn {功能} - 返回布尔来表示一个成功或失败的验证 .

错误 {String} - 一个可以指定自定义错误消息的可选字符串. : 属性 内部错误信息将替换为属性名称 .

import { Validator } from '@chantouchsek/validatorjs'

Validator.register(
  'telephone',
  (value: unknown, _requirement: unknown, _attribute: string): boolean =>
    typeof value === 'string' && /^\d{3}-\d{3}-\d{4}$/.test(value),
  'The :attribute is not in the format XXX-XXX-XXXX.',
)

const validation = new Validator({ phone: '123-456-7890' }, { phone: 'required|telephone' })
validation.passes() // => true
const invalid = new Validator({ phone: '123' }, { phone: 'required|telephone' })
invalid.fails() // => true
invalid.errors.first('phone') // => 'The phone is not in the format XXX-XXX-XXXX.'

回电收到 (value, requirement, attribute)。没有参数的规则接收 undefined 作为它的要求。普通自定义规则跳过缺失/空值;将其与 required,或使用 registerImplicit 习惯规则它必须运行在空输入上。所有验证人都共享登记.

同步验证

登记一条同步规则,该规则接受回复召回作为第四个规则参数。召回一次,包括失败;返回规则中的承诺不会自动解决验证问题.

import { Validator } from '@chantouchsek/validatorjs'

type Respond = (passed?: boolean, message?: string) => void
Validator.registerAsync(
  'username_available',
  (username: string, _requirement: unknown, _attribute: string, respond: Respond): void => {
    setTimeout(() => {
      if (username === 'taken') respond(false, 'Username has already been taken.')
      else respond()
    }, 0)
  },
  'The :attribute is unavailable.',
)

const validator = new Validator(
  {
    username: 'taken',
  },
  {
    username: 'required|min:3|username_available',
  },
)

const passed = await validator.passesAsync()
passed // => false
validator.errors.first('username') // => 'Username has already been taken.'

此示例使用顶级 await 在ES模块中运行;也可以在其中运行 async 函数. passesAsync() 决定 true 或者说 false 审定完成后; 读取 errors 财务报告和审定财务报表 errorCount 之后的个案。时抛出错误援引验证,例如未知规则,拒绝承诺,而不是解决 false。随后在应用程序管理的计时器中推出的例外情况不是自动抓取,而自定义的async规则仍然必须调用他们的回回回复.

它还支持同步规则而不用单独的包装:

import { Validator } from '@chantouchsek/validatorjs'

const validator = new Validator({ email: '[email protected]' }, { email: 'required|email' })
const passed: boolean = await validator.passesAsync()
passed // => true
validator.errors.all() // => {}

回调 API 仍然可用: 当 ASync 规则存在时, passes(callback) 财务报告和审定财务报表 fails(callback) 需要回话. checkAsync(onPass, onFail) 处理两个成果和回报 void。完成一次验证,然后启动另一次验证同样的情况。一项从未回应的习惯规则仍然有待验证; passesAsync() 不添加超时或采用从习惯规则中返回的许诺.

与有效输入合作

使用 validated() 方法只检索经验证的数据,并过滤所提供的规则中没有的属性.

import { Validator } from '@chantouchsek/validatorjs'

const validation = new Validator(
  {
    age: 28,
    email: '[email protected]',
    gender: 'male',
    name: 'John',
  },
  {
    age: 'min:18',
    name: 'required',
  },
)
validation.validated() // => { name: 'John', age: 28 }

validated() 当当前验证失败时,方法会出错.

import { Validator } from '@chantouchsek/validatorjs'

const validation = new Validator(
  {
    age: 28,
    email: '[email protected]',
    gender: 'male',
    name: 'John',
  },
  {
    age: 'min:40',
    name: 'required',
  },
)
validation.validated() // throws: Validation failed!

validated() 也进行同步验证。它的第一个回电收到过滤后的数据作为其第一个参数;第二个回调处理失败.

import { Validator } from '@chantouchsek/validatorjs'

type Respond = (passed?: boolean, message?: string) => void
Validator.registerAsync('allowed_name', (value: string, _requirement: unknown, _attribute: string, respond: Respond): void => {
  setTimeout(() => respond(value !== 'blocked'), 0)
}, 'The :attribute is blocked.')

const validation = new Validator(
  {
    age: 28,
    email: '[email protected]',
    gender: 'male',
    name: 'John',
  },
  {
    age: 'min:18',
    name: 'required|allowed_name',
  },
)
const data = await new Promise<Record<string, unknown>>((resolve, reject) => {
  validation.validated(
    (validated: Record<string, unknown>) => resolve(validated),
    () => reject(new Error('Validation failed')),
  )
})
data // => { name: 'John', age: 28 }

对于嵌入式数据,将规则放入您想要返回的叶地:

import { Validator } from '@chantouchsek/validatorjs'

const input = {
  user: { name: 'Ada', secret: 'hidden' },
  items: [{ sku: 'A1', price: 10, internal: 'hidden' }],
  extra: 'hidden',
}
const rules = { 'user.name': 'required', 'items.*.sku': 'required', 'items.*.price': 'numeric' }
new Validator(input, rules).validated() // => { user: { name: 'Ada' }, items: [{ sku: 'A1', price: 10 }] }

validated() 再次检查输入并返回一个 JSON 克隆投影, 不类型强制或推断输出类型。使用 JSON 兼容输入。目前的限制 : 校验只有数组母程序可以删除其元素, 未规则的对象可以保留作为空容器,以及 null 由于无法预测全部输入。使用叶可预测的过滤规则;这种方法不是一个通用的消毒器.

错误消息

此构造器会自动生成错误消息, 用于验证规则失败 .

如果出现错误, 验证器实例将拥有其错误带有错误消息的属性对象对于所有失败的属性。方法与属性错误属性对象为:

第一(属性)

返回属性的第一个错误消息,或 undefined 不存在时

.get(属性)

返回属性错误消息数组,如果没有错误,则返回空数组

全部( )

返回包含所有失败属性的错误消息的对象

.has( 属性)

如果属性存在错误消息, 返回为真, 否则为假

错误

关于验证器实例的失败规则数量( E)validation.errorCount, (中文(简体) ), 不是财产在 validation.errors。。。 .

import { Validator } from '@chantouchsek/validatorjs'

const input = { email: 'invalid' }
const rules = { email: 'required|email' }
const validation = new Validator(input, rules)
validation.fails()
validation.errors.first('email') // => 'The email format is invalid.'
validation.errors.get('email') // => ['The email format is invalid.']

自定义错误消息

第三个参数中的 Pass 覆盖 customMessages 属性。使用规则所有字段的名称,或 rule.attribute 对于特定的领域.

import { Validator } from '@chantouchsek/validatorjs'

const input = {
  name: '',
}

const rules = {
  name: 'required',
}

const validation = new Validator(input, rules, {
  customMessages: { required: 'You forgot to give a :attribute' },
})
validation.passes() // => false
validation.errors.first('name') // => 'You forgot to give a name'

一些验证器有字符串和数字版本. 你也可以改变它们.

import { Validator } from '@chantouchsek/validatorjs'

const input = {
  username: 'myusernameistoolong',
}

const rules = {
  username: 'max:16',
}

const validation = new Validator(input, rules, {
  customMessages: {
    max: {
      string: 'The :attribute is too long. Max length is :max.',
    },
  },
})
validation.passes() // => false
validation.errors.first('username') // => 'The username is too long. Max length is 16.'

您甚至可以在每个属性的基础上提供错误消息 ! 只要设置信件的密钥“ 验证器. 属性 ”

import { Validator } from '@chantouchsek/validatorjs'

const input = { email: '', name: '' }
const rules = { email: 'required', name: 'required' }

const validation = new Validator(input, rules, {
  customMessages: { 'required.email': 'Without an :attribute we can\'t reach you!' },
})

validation.passes() // => false
validation.errors.first('name') // => 'The name field is required.'
validation.errors.first('email') // => 'Without an email we can\'t reach you!'

自定义属性名称

使用自定义属性名称的配置

import { Validator } from '@chantouchsek/validatorjs'

const validator = new Validator(
  { form: { name: null } },
  { form: { age: 'required', name: 'required' } },
  {
    customAttributes: { form: { name: 'Username' } },
    customMessages: {
      required: 'The :attribute must be filled.',
    },
  },
)
if (validator.fails())
  validator.errors.first('form.name') // => 'The Username must be filled.'

要在错误消息中显示自定义的“ 友好” 属性名称, 请使用 .setAttributeNames()

import { Validator } from '@chantouchsek/validatorjs'

const validator = new Validator({ name: '' }, { name: 'required' })
validator.setAttributeNames({ name: 'custom_name' })
if (validator.fails())
  validator.errors.first('name') // => 'The custom_name field is required.'

或者,您可以使用 attributes 属性.

您也可以配置自定义属性 formatter :

import { Validator } from '@chantouchsek/validatorjs'

// Configure global formatter.
Validator.setAttributeFormatter((attribute: string) => {
  return attribute.replace(/_/g, ' ')
})

// Or configure formatter for particular instance.
const validator = new Validator({ first_name: '' }, { first_name: 'required' })
validator.setAttributeFormatter((attribute: string) => {
  return attribute.replace(/_/g, ' ')
})
if (validator.fails())
  validator.errors.first('first_name') // => 'The first name field is required.'

注意:默认情况下,所有字符将被替换为空格.

语言支持

本地人被捆绑在公共软件包条目中. 使用节点或节点中命名的导入浏览器捆绑器; 没有单独的 dist/lang/*.js 需要导入。英语是初始默认 . LangTypes 列出所支持的语言代码.

import type { ValidatorOptions } from '@chantouchsek/validatorjs'
import { Validator } from '@chantouchsek/validatorjs'

const previousLocale = Validator.getDefaultLang()
const options: ValidatorOptions = { locale: 'fr', customAttributes: { name: 'Nom' } }
const validation = new Validator({ name: '' }, { name: 'required' }, options)
validation.fails() // => true
validation.errors.first('name') // => 'Le champ Nom est requis.'
Validator.useLang(previousLocale)

目前,正在建造一个验证器,其中 locale 也改变全局默认值适用于后来的验证人和习惯规则登记。设置或恢复默认值在共享应用程序中明确。使用支持的地块; 未知代码没有自动后退。要设置后续实例的默认值 :

import { Validator } from '@chantouchsek/validatorjs'

const previousLocale = Validator.getDefaultLang()
Validator.useLang('km')
Validator.getDefaultLang() // => 'km'
const validation = new Validator({ name: '' }, { name: 'required' })
validation.fails() // => true
validation.errors.first('name') // => 'ឈ្មោះ ត្រូវតែបញ្ចូលជាដាច់ខាត។'
Validator.useLang(previousLocale)

getMessages 返回共享语言词典。在压倒一切的消息之前复制它与 setMessages; 保存其他模板,这样不相关的规则仍然可以渲染:

import { Validator } from '@chantouchsek/validatorjs'

const original = Validator.getMessages('en')
Validator.setMessages('en', { ...original, required: 'Whoops, :attribute is required.' })
const validation = new Validator({}, { name: 'required' }, { locale: 'en' })
validation.fails() // => true
validation.errors.first('name') // => 'Whoops, name is required.'
Validator.setMessages('en', original)

如果你没有看到支持你的语言,请添加一个 src/lang来啊!

发展

使用pnpm 10.26.0和Node.js 22.22.2+, 24.15.0+,或26+来进行开发. 这些要求来自开发工具;已出版的成套文件仍然支持节点.js ^12.20.0 || >=14.13.0。。。 .

pnpm install --frozen-lockfile
pnpm test:cov
pnpm typecheck
pnpm lint
pnpm build
pnpm test:package

包检查将本地沥青球安装到临时项目中,核实无害环境管理和普通JS行为,并检查两种声明格式。检查一个老人消费者运行时间,将其节点可执行文件传递给 pnpm test:package /path/to/node· ; 检查本身必须在开发节点版本上运行.

许可证

根据麻省理工学院许可证获释

贷项

校验器 Js 由 Chantouch Sek 重写

电子邮件 : [email protected] 页面存档备份,存于互联网档案馆

微博 @ DevidCs83 (英语)

网站: 钱通克

版本与发布记录

@chantouchsek/validatorjs 共发布 57 个版本，首次发布于 2020/07/23；过去 12 个月发布了 5 个版本。

版本	发布日期	距今
`2.3.0`latest	2026/10/17	23 天前
`2.2.8`	2026/04/23	6 个月前
`2.2.7`	2025/12/17	10 个月前
`2.2.6`	2025/12/17	10 个月前
`2.2.5`	2025/12/13	10 个月前
`2.2.4`	2024/09/20	2 年前

关于 @chantouchsek/validatorjs 的常见问题

@chantouchsek/validatorjs 是什么？

校验器.js库使得JavaScript中的数据验证在浏览器和Node.js中都非常容易.

如何安装 @chantouchsek/validatorjs？

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

@chantouchsek/validatorjs 支持 TypeScript 吗？

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

@chantouchsek/validatorjs 支持 ESM 还是 CommonJS？

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

@chantouchsek/validatorjs 需要什么版本的 Node.js？

package.json 的 engines 字段要求 Node.js ^12.20.0 || >=14.13.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

@chantouchsek/validatorjs 可以商用吗？

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

@chantouchsek/validatorjs 的下载量有多少？

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

@chantouchsek/validatorjs 还在维护吗？

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

npm install @chantouchsek/validatorjs

pnpmpnpm add @chantouchsek/validatorjs
yarnyarn add @chantouchsek/validatorjs
bunbun add @chantouchsek/validatorjs

peer 依赖libphonenumber-js ^1.13.15可选

npm 7+ 与 pnpm 8+ 会自动安装必需的 peer 依赖，Yarn 需手动安装。

在你的项目目录中运行此命令。

近 30 天下载

2,891

约 2891 次日均 96 次

统计周期 2026/10/10 – 2026/11/08
数据来自 npm 官方下载统计，今天更新

最新版本2.3.0发布于 23 天前

开源许可MIT宽松许可

包体积926 kB13 个文件 · 解压后

运行依赖1 个另有 1 个 peer 依赖

模块格式ESM + CJS无副作用，可 tree-shake

TypeScript自带类型

Node.js^12.20.0 || >=14.13.0

发布版本57 个近 12 个月 5 个

首次发布2020/07/236 年前

元数据更新2026/10/17

每一个软件包背后，
都有分享与创造的人。