iodine

碘

Iodine.js 是一个微型客户端验证库。它没有依赖性，可以单独使用或作为框架的一部分使用。 Iodine 还支持可链接规则，允许您验证一条（或多条）数据是否满足多个条件。

升级中

Iodine 8+ 版本进行了重大重写，其中包含许多重大更改。因此，建议现有项目继续使用版本 7（或更低版本），而版本 8（或更高版本）应保留给较新的项目。

安装

将 Iodine 引入项目的最简单方法是通过 CDN（请务必更新内部版本号）：

 < script src =" https://cdn.jsdelivr.net/npm/@caneara/[email protected]/dist/iodine.min.umd.js " defer >  script >

您还可以通过 NPM 将 Iodine 拉入您的项目：

 npm i @ caneara / iodine 

用法

Iodine 会自动添加到window命名空间中，使其可以在任何地方使用。如果您的项目不涉及编译或导入，这是推荐使用 Iodine 的方法。即使您的项目确实涉及编译，通常也更容易使用添加到window命名空间的实例。

或者，如果您习惯使用导入，或者您想创建自己的实例，那么您可以像这样导入 Iodine：

 import Iodine from '@caneara/iodine' ;

const instance = new Iodine ( ) ; 

基本验证

Iodine 包含一系列验证规则，您可以通过其关联方法访问它们。这样可以快速、轻松地检查某个项目是整数还是日期。

Iodine 的规则以assert为前缀。因此，要检查某个项目是否为integer ，您可以使用以下代码：

 let item_1 = 7 ;
let item_2 = 'string' ;

Iodine . assertInteger ( item_1 ) ; // true
Iodine . assertInteger ( item_2 ) ; // false

请参阅下文，了解 Iodine 包含的验证规则的完整列表。

高级验证

虽然检查项目是否符合单个验证规则可能很有用，但您通常会想要检查项目是否符合多个规则。例如，电子邮件地址可能是必需的，必须是字符串，并且必须满足电子邮件地址正则表达式。

为了满足这些需求，Iodine 提供“单项检查”和“多项检查”...

单项检查

如果您有一个项目需要根据多个规则进行测试（例如上面描述的电子邮件地址示例），则首选此方法。要执行“单项检查”，请调用主assert方法。该方法有两个参数。第一个是要检查的项目。第二个是一array应按顺序运行的验证规则，例如

 let item_1 = 7 ;
let item_2 = 'string' ;

Iodine . assert ( item_1 , [ 'required' , 'integer' ] ) ;
Iodine . assert ( item_2 , [ 'required' , 'integer' ] ) ;

正如您在示例中看到的，验证规则是使用strings表示的。要查找验证规则的string表示形式，请查看现有列表。

与单独的断言（返回boolean ）不同， assert方法返回一个包含报告的object 。当该项目通过所有规则时，您将得到：

 {
    valid : true ,
    rule  : '' ,
    error : '' ,
} ;

如果项目验证失败，报告将包含其未能满足的第一条规则以及关联的错误消息：

 {
    valid : false ,
    rule  : 'integer' ,
    error : 'Value must be an integer' ,
} ;

多项检查

当您需要根据一堆不同的验证规则检查多个项目时，例如提交包含多个字段的表单时，首选此方法。

与“单项检查”一样，您应该调用assert方法，但是对于这两个参数，您将需要提供一个object 。第一个对象应包含要验证的项目，而第二个对象应包含每个项目的规则，例如

 const items = {
    name     : 5 ,
    email    : '[email protected]' ,
    password : 'abcdefgh' ,
} ;

const rules = {
    name     : [ 'required' , 'string' ] ,
    email    : [ 'required' , 'email' ] ,
    password : [ 'required' ] ,
} ;

Iodine . assert ( items , rules ) ;

与“单项检查”不同，该报告略有不同。它包含一个顶级valid密钥，可让您轻松检查是否一切都通过或失败。然后它包含一个fields键，其中包含每个项目的子报告。子报告与“单项检查”获得的内容相同。这是上面显示的代码示例的报告：

 {
    valid  : false ,
    fields : {
        name : {
            valid : false ,
            rule  : 'string' ,
            error : 'Value must be a string' ,
        } ,
        email : {
            valid : true ,
            rule  : '' ,
            error : '' ,
        } ,
        password : {
            valid : true ,
            rule  : '' ,
            error : '' ,
        }
    } ,
} ; 

附加参数

有些规则需要额外的参数，例如

 let item_1 = 7 ;
let item_2 = 4 ;

Iodine . assertMin ( item_1 , 5 ) ; // true
Iodine . assertMin ( item_2 , 5 ) ; // false

对于高级验证，您可以通过将参数附加到带有分号分隔符的规则来提供参数，例如

 let item_1 = 7 ;
let item_2 = 4 ;

Iodine . assert ( item_1 , [ 'required' , 'integer' , 'min:5' ] ) ;
Iodine . assert ( item_2 , [ 'required' , 'integer' , 'min:5' ] ) ;

或者，如果您愿意，可以将规则作为object提供，而不是用分号分隔的string ：

 Iodine . assert ( 8 , [ 'required' , 'integer' , { rule : 'min' , param : 7 } , 'max:10' ] ) ; 

可选值

对于高级验证，您可能希望允许可选值。 Iodine 通过optional规则支持这一点：

 let item_1 = 7 ;
let item_2 = null ;
let item_3 = 'string' ;

Iodine . assert ( item_1 , [ 'optional' , 'integer' ] ) ;
Iodine . assert ( item_2 , [ 'optional' , 'integer' ] ) ;
Iodine . assert ( item_3 , [ 'optional' , 'integer' ] ) ;

重要提示：如果您希望允许可选值，那么它必须是数组中的第一个规则。

自定义错误

Iodine 包含一组默认的英语错误消息。但是，您可以通过setErrorMessages方法轻松替换它们。此方法需要一个参数，该参数是包含消息的object 。有关示例，请参阅 Iodine 的构造函数。

发生错误时，Iodine 会自动替换[FIELD]和[PARAM]占位符。因此，您应该在新错误消息中的适当位置插入这些占位符，例如

 Iodine . setErrorMessages ( { same : `[FIELD] must be '[PARAM]'` } ) ;   // English
Iodine . setErrorMessages ( { same : `[FIELD] doit être '[PARAM]'` } ) ; // French

单一错误

在许多情况下，您不需要替换所有错误消息。相反，您会想要更新一个或添加一个新的。为此，您应该调用setErrorMessage例如

 Iodine . setErrorMessage ( 'passwordConfirmation' , 'Does not match password' ) ;

按字段的自定义错误

有时，可能需要为字段定义特定的错误消息，或者需要与所使用的变量名称不同的字段标签。

要实现此目的，请将一个对象传递给包含规则作为属性和自定义错误消息作为值的assert方法，例如

 Iodine . assert ( value , [ 'required' ] , { 'required' : 'The "Label" must be present.' } ) ;

您还可以对多个字段使用相同的方法，例如

 let items = {
    name : '' ,
} ;

let rules = {
    name : [ 'required' ]
} ;

let errors = {
    name : {
        required : 'The "Label" must be present.'
    }
} ;

Iodine . assert ( items , rules , errors ) ;

默认字段名称

由于“单项检查”不支持字段名称，因此 Iodine 使用默认值（即“值”）。如果“Value”不合适，那么您可以调用setDefaultFieldName方法并提供替代string值来代替，例如

 Iodine . setDefaultFieldName ( 'Valeur' ) ;

请注意，您必须在调用assert之前调用setDefaultFieldName 。

可用规则

可以使用以下验证规则：

规则	字符串键	描述
断言之后（日期/整数）	'后'	验证该项目是否是给定Date或时间戳之后的Date
断言AfterOrEqual（日期/整数）	'之后或等于'	验证该项目是否是晚于或等于给定Date或时间戳的Date
断言数组	'大批'	验证该项目是一个array
断言之前（日期/整数）	'前'	验证该项目是否是给定Date或时间戳之前的Date
断言BeforeOrEqual（日期/整数）	'之前或等于'	验证该项目的Date是否早于或等于给定Date或时间戳
断言布尔值	'布尔值'	验证该项目是true还是false
断言日期	'日期'	验证该项目是否为Date对象
断言不同（值）	'不同的'	验证该项目与提供的值不同（使用松散比较）
断言结束（值）	‘结束’	验证该项目是否以给定值结尾
断言电子邮件	'电子邮件'	验证该项目是否是有效的电子邮件地址
断言错误	‘虚假’	验证该项是否为false 、 'false' 、 0或'0'
断言（数组）	'在'	验证该项目是否在给定array内
断言整数	‘整数’	验证该项是否为integer
断言Json	'json'	验证该项目是可解析的 JSON 对象string
断言最大长度（限制）	'最大长度'	验证项目的字符长度不超过给定的限制
断言最小长度（限制）	'最小长度'	验证项目的字符长度是否低于给定的限制
断言最大（限制）	'最大限度'	验证该项目的数值不超过给定的限制
断言最小（限制）	'分钟'	验证该项目的数值不低于给定的限制
断言NotIn（数组）	'不在'	验证该项目不在给定array内
断言数字	'数字'	验证该项目是number还是数字string
断言可选	'选修的'	允许可选值（仅用于多重检查）
断言正则表达式匹配(exp)	'正则表达式匹配'	验证该项目是否满足给定的正则表达式
断言必需	'必需的'	验证该项不为null 、 undefined或空string
断言相同（值）	'相同的'	验证该项目与提供的值相同（使用松散比较）
断言启动（值）	'开始于'	验证该项目是否以给定值开头
断言字符串	'细绳'	验证该项目是一个string
断言真相	“真实”	验证该项是否为true 、 'true' 、 1或'1'
断言网址	'网址'	验证该项目是否是有效的 URL
断言Uuid	'uuid'	验证该项目是否为UUID

检查测试以获取如何使用每个规则的示例。

自定义规则

Iodine 允许您通过rule方法添加自己的自定义验证规则。该方法接受两个参数。第一个是规则的名称。第二个是 Iodine 在调用规则时应该执行的closure ，例如

 Iodine . rule ( 'lowerCase' , ( value ) => value === value . toLowerCase ( ) ) ;

重要提示：Iodine 会自动将规则名称的第一个字母变为大写，并添加前缀“assert”。因此，您应该避免自己添加前缀，例如

 Iodine . rule ( 'lowerCase' ) ;       // right
Iodine . rule ( 'assertLowerCase' ) ; // wrong

如果您的规则需要接受参数，只需将其作为第二个参数包含在closure中，例如

 Iodine . rule ( 'equals' , ( value , param ) => value == param ) ;

您还可以为自定义规则添加错误消息，例如

 Iodine . rule ( 'equals' , ( value , param ) => value == param ) ;
Iodine . setErrorMessage ( 'equals' , "[FIELD] must be equal to '[PARAM]'" ) ; 

异步规则

以前版本的 Iodine 支持使用async / await异步自定义规则。此后已将其删除，以使库更易于维护。如果您使用异步规则，那么首选策略是首先执行异步逻辑，存储结果，然后让 Iodine 验证它。

贡献

感谢您考虑为 Iodine 做出贡献。欢迎您提交包含附加规则的 PR，但是要被接受，它们必须解释它们的作用、对他人有用，并包含适当的测试以确认它们正确工作。

拉取项目后，安装依赖项：

npm install

运行测试

npm run test 

执照

麻省理工学院许可证 (MIT)。请参阅许可证文件以获取更多信息。