# haor-validator

**Repository Path**: Luomenghao/haor-validator

## Basic Information

- **Project Name**: haor-validator
- **Description**: 使用typesript封装的一套表单验证，灵活、通用；
- **Primary Language**: TypeScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2023-12-15
- **Last Updated**: 2023-12-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Haor-Validator 表单验证器

当前最新版本： `V1.0.2`（发布日期：2023-12-14）

### 一、安装

```javascript
// npm
npm install haor-validator -S;
// yarn
yarn add haor-validator -S
```

### 二、使用

#### 基本使用流程说明

```bash
1. 定义字段rules规则；
2. new Validator实实例，并传入rules参数；
3. 调用实例的 validate方法，传入data数据进行验证；
```

> 小提示：内部验证顺序则是 `required` → `pattern` → `validator`

#### 字段 rule 属性说明

| 属性      | 类型              | 说明                                                                              | 备注                                                       |
| --------- | ----------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| required  | `boolean`         | 是否必填                                                                          | [null, undefined, NaN, '']，其中包含任意一个，统一视为空值 |
| pattern   | `string` `RegExp` | 类型模式，可传入对应的类型或正则表达式，<br />如使用正则，则需要加 `message `属性 | 支持的类型： 参看下方：`类型说明表`                        |
| message   | `string`          | 验证失败错误消息                                                                  | 不传递，默认匹配`pattern`对应的类型 message                |
| validator | `functioin`       | 自定义验证函数，同步异步都可使用                                                  |                                                            |
| params    | `array`           | 扩展参数，用户验证如范围，最大、最小                                              | 参考下方`类型说明表`，注意参数顺序！                       |

#### 1、基础使用

```javascript
import { Validator } from 'kyber-mom-validator'; // 引入库

// 1、验证规则
const rules = {
	username: {
		required: true,
		pattern: 'userName',
	},
	// 一个字段可使用多个规则
	password: [
		{
			required: true,
			pattern: 'password',
		},
		{
			// 自定义验证
			validator: (value, rule, cb) => {
				/**
				 * 自定义验证逻辑
				 * 成功 cb();
				 * 失败 cb(new Error('错误信息'))
				 */
			},
		},
	],
};

///2、创建一个实例，传入规则参数
const v1 = new Validator(rules);

///3、调用验证方法
v1.validate(
	{
		username: '11',
		password: '111',
	},
	function (result, error) {
		if (result) {
			console.log('成功咯~~');
		} else {
			console.log('error:', error);
		}
	},
);
```

#### 2、使用正则

```javascript
import { Validator } from 'kyber-mom-validator';

// 使用正则
const validator = new Validator({
	username: {
		// 注意：使用正则需要自己添加message
		pattern: /^[a-zA-Z0-9_-]{4,16}$/,
		message: '请输入正确的用户名',
	},

	// 一个字段可使用多个规则
	password: {
		required: true,
		pattern: 'password',
	},
});
validator
	.validate(data)
	.then(() => {})
	.catch((err) => {});
```

#### 3、使用自定义验证

```javascript
import { Validator } from 'kyber-mom-validator';

// 使用正则
const validator = new Validator({
	username: {
		required: true,
		validator: function (data, rule, cb) {
			if (data && data.length < 5) {
				return cb(new Error('用户名应该大于5位'));
			}
			cb(); // 没有错误则直接调用cb，无需传参
		},
	},

	// 异步
	password: {
		required: true,
		validator: function (data, rule, cb) {
			if (data && data.length < 5) {
				// 模拟异步
				setTimeout(() => {
					cb(new Error('用户密码格式错误'));
				}, 2000);
				return;
			}
			cb();
		},
	},
});
validator
	.validate(data)
	.then(() => {})
	.catch((err) => {});
```

#### 4、完整例子

`validate`方法可以使用回调、也可以使用 `Promise`

```javascript
import { Validator } from 'kyber-mom-validator';
const v1 = new Validator({
	nickName: {
		params: ['昵称'],
		// 自定义验证器
		validator: function (value, rule, cb) {
			if (!value || value.length === 0) {
				cb(new Error('请输入昵称'));
				return;
			}

			// 模拟异步
			if (value === 'admin') {
				setTimeout(() => {
					cb(new Error('昵称已存在'));
				}, 1000);
				return;
			}
			cb();
		},
	},
	userName: {
		pattern: 'cnName',
		params: ['姓名'],
	},
	age: {
		pattern: 'rangeNumber',
		params: ['年龄', 18, 60],
	},
	phone: {
		pattern: 'phone',
		params: ['联系电话'],
	},
	like: {
		required: true,
		pattern: 'include',
		params: ['爱好', ['吃饭', '睡觉', '打豆豆']],
	},
	remark: {
		required: true,
		pattern: 'maxLength',
		params: ['备注信息', 20],
	},
});
v1.validate({
	nickName: '',
	realName: '张三',
	age: 18,
	phone: '13566667777',
	like: '吃饭',
	remark: '备注备注~~',
})
	.then((data) => {
		console.log('验证成功啦~~~');
	})
	.catch((err) => {
		console.log(err);
		console.log(v1);
	});
```

#### 5、validate 方法使用 Promise 或 Callback

```javascript
const validator = new Validator({});
// 1、使用callback回调
validator.validate({}, (result, error) => {
	if (result) {
		console.log('成功！');
	} else {
		console.log('error:', error);
	}
});

///2、使用Promise
validator
	.validate({})
	.then(() => {
		console.log('成功！');
	})
	.catch((error) => {
		console.log('error:', error);
	});
```

### 三、方法说明

| 方法      | 说明     | 参数                                                         | 返回值  | 备注                                                                      |
| --------- | -------- | ------------------------------------------------------------ | ------- | ------------------------------------------------------------------------- |
| validate  | 验证表单 | validate(data: object, callback?: (result, error) => {})     | Promise | 可使用`promise`或者`callback`回调, 注意是需要所有的字段验证完了才结束验证 |
| setLang   | 设置语言 | setLang(lang: 'zh' \| 'en'): void                            | void    | 目前支持中文、英文                                                        |
| onSuccess | 成功监听 | onSuccess(fieldName: string): void                           | void    | -                                                                         |
| onError   | 失败监听 | onError(fieldName: string, message: string, data: any): void | void    | -                                                                         |

### 四、类型说明

| 类型                 | 值            | 参数（注意传递顺序）         | 备注                                                                          |
| -------------------- | ------------- | ---------------------------- | ----------------------------------------------------------------------------- |
| 非空                 | `notNull`     | [描述]                       | ↓ 每个必须按顺序传递, 描述主要是提供给 `message` 模板使用，如果不用，传控占位 |
| 邮箱                 | `email`       | [描述]                       |                                                                               |
| 用户名               | `userName`    | [描述]                       |                                                                               |
| 中文姓名             | `cnName`      | [描述]                       |                                                                               |
| xxx-xxxxxxx 座机电话 | `tel`         | [描述]                       |                                                                               |
| 手机号               | `phone`       | [描述]                       |                                                                               |
| 日期                 | `date`        | [描述]                       |                                                                               |
| IP 地址              | `ip`          | [描述]                       |                                                                               |
| 布尔值               | `boolean`     | [描述]                       |                                                                               |
| 颜色十六进制         | `colorHex`    | [描述]                       |                                                                               |
| 字符最小长度         | `minLength`   | [描述，最小长度]             |                                                                               |
| 字符最大长度         | `maxLength`   | [描述，最大长度]             |                                                                               |
| 字符长度范围         | `rangeLength` | [描述，最小长度，最大长度]   |                                                                               |
| 数字最小值           | `min`         | [描述，最小值]               |                                                                               |
| 数字最大值           | `max`         | [描述，最大值]               |                                                                               |
| 数字范围             | `rangeNumber` | [描述，最小值，最大值]       |                                                                               |
| 整数                 | `intNumber`   | [描述]                       |                                                                               |
| 浮点数               | `floatNumber` | [描述]                       |                                                                               |
| 负数                 | `minusNumber` | [描述]                       |                                                                               |
| 包含某一个值         | `include`     | [描述，[值 1， 值 2， 值 3]] |                                                                               |

### 五、多语言支持

> 每次调用表单验证的时，如有错误的 message，则会根据多语言来进行匹配；

| 语言 | 值         |
| ---- | ---------- |
| zh   | 中文/zh-CN |
| en   | 英文/en-US |

### 六、版本更新说明

##### v1.0.2 (2023.12.14)

```bash
1、README文档完善；
```

##### v1.0.0 (2023.12.13)

```bash
1、修复bug；
```

##### v1.0.0 (2023.12.12)

```bash
1、初始版本
```