# @caneara/iodine 中文文档

规范地址：https://npmcn.com/package/%40caneara/iodine/

版本：8\.5\.0
npm 元数据更新时间：2023-07-31T18:24:50.375Z
中文译文更新时间：2026-11-09T01:00:28.288Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40caneara/iodine
原文对照：https://npmcn.com/package/%40caneara/iodine/?lang=original
项目主页：https://github.com/caneara/iodine#readme
源码仓库：https://github.com/caneara/iodine

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：172 kB，16 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2022-11-04T11:02:50.432Z
- 最新版本发布：2023-07-31T18:24:50.247Z
- 近 30 天下载量：6030（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 0 个）

## 中文简介

一个微客户端验证库

## 安装

```sh
npm install @caneara/iodine
```

也可以使用：`pnpm add @caneara/iodine`、`yarn add @caneara/iodine`、`bun add @caneara/iodine`

## README

# 碘

Iodine.js是一个微型客户端验证库. 它没有依赖性,可单独使用或作为框架的一部分使用。 碘也支持可连锁规则,允许您验证一个(或数个)数据是否符合多条标准.

## 升级

碘的8+版本涉及一次重大的重写,多次突破性修改. 因此,建议现有项目继续使用 [版本 7](https://npmcn.com/package/%40caneara/iodine/LEGACY.md) (或更低),而第8版(或更高)应保留给较新的项目.

## 安装

将碘拉入您项目的最简单方法是通过一个CDN(确保更新建筑编号):

```html
<script src="https://cdn.jsdelivr.net/npm/@caneara/iodine@8.5.0/dist/iodine.min.umd.js" defer></script>
```

您也可通过国家防范机制将碘引入您的项目:

```js
npm i @caneara/iodine
```

## 使用量

碘自动添加到 `window` 名称空间,在任何地方都可以使用。 如果您的项目不涉及汇编或进口,则推荐使用碘。 即使你的项目确实涉及汇编,仅仅使用添加的示例通常也比较容易 `window` 名称空间.

或者,如果使用进口品自在,或者想创建自己的实例,那么您可以这样进口碘:

```js
import Iodine from '@caneara/iodine';

const instance = new Iodine();
```

## 基本验证

碘包括一系列验证规则,你可以通过它们的相关方法访问. 这使得快速和容易地检查某个项目是例如整数还是日期.

碘化物的规则有前缀 `assert`因此,检查某件物品是否属于 `integer`,你会使用以下代码:

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

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

[见下文](https://npmcn.com/package/%40caneara/iodine/#readme-available-rules) 包括碘的鉴定规则.

## 高级验证

在检查某一项是否符合单个验证规则可能有用的同时,你往往会想检查某一项是否符合多个规则. 例如,可能需要电子邮件地址,必须是字符串,而且必须满足电子邮件地址正则表达式.

为了解决这些需要,碘提供了"单项检查"和"多项检查"......

### 单项检查

如果您有一个项目需要对照多个规则进行测试( 如上文所述的电子邮件地址示例) , 则选择此方法 。 要进行“ 单项检查”, 请拨打主机 `assert` 方法。 这种方法需要两个参数. 首先是要检查的项目。 第二个是 `array` (b) 应按顺序运行的验证规则,例如:.

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

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

从实例中可以看出,验证规则是使用 `strings`。寻找 `string` 代表审定规则, [审查现有清单](https://npmcn.com/package/%40caneara/iodine/#readme-available-rules)。 。 。 .

不同于个人的断言(它返回a `boolean`页:1 `assert` 方法返回一个 `object` 载有一份报告。 当物品通过所有规则, 你会得到这个:

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

如果项目无法验证,报告将包含它未能满足的第一个规则,以及相关的错误消息:

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

### 多个项目检查

当您需要对照一组不同的验证规则来检查多个项目时,例如当提交包含多个字段的表格时,倾向于采用这种方法.

就像"单项检查"一样,你应该打电话给 `assert` 但是,对于两个参数,您需要提供 `object`。第一个对象应包含有待验证的项目,而第二个对象应包括每个项目的规则,例如:.

```js

const items = {
    name     : 5,
    email    : 'test@example.com',
    password : 'abcdefgh',
};

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

Iodine.assert(items, rules);
```

与"单项检查"不同,报告略有不同. 它包含一个顶级 `valid` 键,可以方便地检查是否一切经过或失败。 然后包含一个 `fields` 键,其中包含每个项目的子报告。 子报告是同样的东西 你会得到"单一项目检查"。 以下是上面的代码示例报告:

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

## 其他参数

有些规则需要额外的参数,例如:.

```js
let item_1 = 7;
let item_2 = 4;

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

对于高级验证,您可以通过将参数附加到规则中,例如使用分号分隔符来提供参数.

```js
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` 以分号分隔 :

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

## 可选价值观

对于高级验证,您可能希望允许选择值。 碘能支持这一点 `optional` 规则:

```js
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']);
```

**重要性**: 如果您想要允许可选值, 那么它必须是数组中的第一个规则 .

## 自定义出错

碘包括英语的默认错误信息集. 不过,你很容易通过 `setErrorMessages` 方法。 这种方法需要一个单一参数,即 `object` 包含信件。 见碘水 [构造器](https://npmcn.com/package/%40caneara/iodine/src/iodine.js) 举个例子.

碘将自动取代 `[FIELD]` 财务报告和审定财务报表 `[PARAM]` 错误发生时的占位符。 因此,您应当在您的新错误信息(例如)中的适当位置插入这些占位符.

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

### 单个错误

在许多情况下,你不需要替换所有错误消息. 你会想更新一个 或者增加一个新的。 要做到这一点,你应该打电话 `setErrorMessage` 譬如说.

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

### 按字段分列的自定义错误

有时,可能有必要定义一个字段的特定错误消息,或者需要给一个字段设置与所使用的变量名称不同的标签.

要达到此目的,请将一个对象传递到 `assert` 将规则作为属性和自定义错误消息作为值的方法,例如.

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

也可以对多个字段使用相同的方法,例如:.

```js
let items = {
    name : '',
};

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

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

Iodine.assert(items, rules, errors);
```

### 默认字段名称

由于“ 单项检查” 不支持字段名称, 碘使用默认值( 是“ Vale ” ) 。 如果"Value"不合适,那么你可以打电话 `setDefaultFieldName` 方法和提供替代品 `string` 用于替代的值,例如.

```js
Iodine.setDefaultFieldName('Valeur');
```

请注意,你必须打电话 `setDefaultFieldName` 打电话前 `assert`。 。 。 .

## 现行规则

现有审定规则如下:

| 规则 | 字符串键 | 说明 |
| --- | --- | --- |
| (日期/整数) | 接下来 | 证明该物品是 `Date` 给定后 `Date` 或时间戳 |
| afterOrEqual( 日期/整数) | "OrEqual之后"("OrEqual"),"After OrEqual","OrEqual","OrEqual","OrEqual","OrEqual","OrEqual","OrEqual","Anter OrEqual","Anter OrEqual" | 证明该物品是 `Date` 在一个给定之后或等于 `Date` 或时间戳 |
| 平方阵列 | "阵列" | 验证该物品是否为 `array` |
| 在( 日期/ 整数) 之前 | "之前" (英语) | 证明该物品是 `Date` 在特定时间之前 `Date` 或时间戳 |
| 在OrEqual( 日期/ 整数) 之前 | "在OrEqual之前" (欧平分之前) | 证明该物品是 `Date` 在给定之前或等于 `Date` 或时间戳 |
| 维护 Boolean | "布尔" | 验证物品是否为 `true` 或者说 `false` |
| 日期 | 约会 | 证明该物品是 `Date` 对象 |
| 偏差( 数值) | "不一样" | 验证项目与所提供值的不同( 用途比较松散) |
| professions (数值) | 结尾 | 验证项目以给定值结尾 |
| 声明电子邮件 | "邮件" | 验证项目是否为有效的电子邮件地址 |
| 主张 Falsy | "虚伪" | 验证物品是否为 `false`, (中文(简体) ), `'false'`, (中文(简体) ), `0` 或者说 `'0'` |
| profile( 阵列) | '进' | 验证该物品是否在给定范围内 `array` |
| 固态整数 | "整数" | 验证该物品是否为 `integer` |
| 断言 Json | 贾生 | 验证项目是否为可解析的 JSON 对象 `string` |
| 维护MaxLength( 限制) | "麦克斯·伦斯" | 验证项目字符长度是否超过指定限制 |
| 主张MinLength( 限制) | "明伦斯" | 验证物品的字符长度是否在指定的限制下 |
| profile( 限制) | "马克斯" | 验证项目的数字值是否超过给定的限度 |
| profile( 限制) |  ̅ | 校验项目的数字值是否在给定的限值下 |
| profilenot In( 阵列) | '不进' | 验证物品不在给定范围内 `array` |
| 断言 | 数字 | 验证该物品是否 `number` 或数字 `string` |
| 主张可选 | "选择" | 允许可选值( 只用于多次检查) |
| 声明RegexMatch( exp) | "regexMatch" (游戏) | 验证项目是否满足给定正则表达式 |
| 必需 | "必须" | 证明项目不是 `null`, (中文(简体) ), `undefined` 或为空 `string` |
| 相同( 数值) | 同样的 | 验证项目是否与所提供的值相同( 使用松散比较) |
| profileSartsWith( 数值) | "开始" | 验证项目从给定值开始 |
| 伸缩 | 弦声 | 证明该物品是 `string` |
| 真实性 | "真实" | 验证物品是否为 `true`, (中文(简体) ), `'true'`, (中文(简体) ), `1` 或者说 `'1'` |
| 主张 | "尔" | 验证项目是否为有效的 URL |
| 断言Uuid | "我们" | 证明该物品是 `UUID` |

研究如何使用每项规则的例子.

## 自定义规则

碘允许您通过 `rule` 方法。 这种方法接受两个参数. 其一,为正统之名. 第二个,是 `closure` 碘在调用规则时应当执行,例如:.

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

**重要性**:碘会自动使规则名称的第一个字母大写并用"assert"来前缀. 因此,你应避免增加前缀,例如:.

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

如果您的规则需要接受一个参数, 请在您 `closure` 作为第二个论点,例如:.

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

您也可以为您的自定义规则添加错误消息,例如 .

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

## 同步规则

以前版本的碘支持使用同步自定义规则 `async / await`. 现已删除,以使图书馆更容易维护。 如果您使用同步规则,那么首选策略是先执行同步逻辑,存储结果,然后进行碘验证.

## 捐款

谢谢你考虑给碘化物做贡献 欢迎您提交包含额外规则的公关文件,无论这些规则是否被接受,它们必须解释它们做什么,对他人有用,并包含一个适当的测试,以确认它们的工作正确.

在拉动工程后, 要安装依赖性 :

```bash
npm install
```

做测试

```bash
npm run test
```

## 许可证

麻省理工学院许可证(MIT). 请看 [许可证文件](https://npmcn.com/package/%40caneara/iodine/LICENSE.md) 更多信息.

## 常见问题

### @caneara/iodine 是什么？

一个微客户端验证库

### 如何安装 @caneara/iodine？

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

### @caneara/iodine 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/caneara\_\_iodine 是否存在。

### @caneara/iodine 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @caneara/iodine 可以商用吗？

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

### @caneara/iodine 的下载量有多少？

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

### @caneara/iodine 还在维护吗？

最新版本 8\.5\.0 发布于 2023/08/01（3 年前）；至今共发布 3 个版本，其中过去 12 个月发布了 0 个；首次发布于 2022/11/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。