# 数据验证模块
数据验证模块提供了各种常用的数据验证功能，专为中文开发者优化，支持手机号、身份证、邮箱等多种数据类型的验证。
## 引用方式
### ES6 模块引用
```javascript
import sinma from 'sinmajs';
// 或者使用解构赋值
import { isPhone, isEmail, isIdCard } from 'sinmajs';
```
### CommonJS 引用
```javascript
const sinma = require('sinmajs');
```
### 浏览器直接引用
```html
<script src="https://unpkg.com/sinmajs@latest/dist/sinma.min.js"></script>
<script>
// 直接使用 sinma 对象
console.log(sinma.isPhone('13812345678'));
</script>
```
## API 列表
### isPhone(value, strict) - 手机号验证
验证中国大陆手机号码格式。
#### 参数
- `value` {string} - 待验证的手机号
- `strict` {boolean} - 是否启用严格验证模式，默认 `false`
#### 返回值
- {boolean} - 验证通过返回 `true`，否则返回 `false`
#### 功能代码
```javascript
// 宽松验证：1开头，第二位3-9，总长11位
const phoneRegex = /^1[3-9]\d{9}$/;
// 严格验证：精确匹配运营商号段
const phoneStrictRegex = /^((13[0-3])|(13[5-9])|(14(0|[5-7]|9))|(15([0-3]|[5-9]))|(16(2|[5-7]))|(17[0-8])|(18[0-9])|(19([0-3]|[5-9])))\d{8}$/;
function isPhone(value, strict = false) {
if (typeof value !== 'string') return false;
return strict ? phoneStrictRegex.test(value) : phoneRegex.test(value);
}
```
#### 使用方法
```javascript
// 宽松验证
sinma.isPhone('13812345678'); // true
sinma.isPhone('12345678901'); // false
// 严格验证（精确号段匹配）
sinma.isPhone('13412345678', true); // false (134号段不支持)
sinma.isPhone('13512345678', true); // true
```
#### 使用范例
```javascript
// 表单验证示例
function validatePhoneInput(phone) {
if (!sinma.isPhone(phone)) {
return {
valid: false,
message: '请输入正确的手机号码'
};
}
if (!sinma.isPhone(phone, true)) {
return {
valid: false,
message: '该手机号码号段暂不支持'
};
}
return {
valid: true,
message: '验证通过'
};
}
// 实际应用
const result = validatePhoneInput('13812345678');
console.log(result); // { valid: true, message: '验证通过' }
```
---
### isEmail(value) - 邮箱验证
验证邮箱地址格式是否正确。
#### 参数
- `value` {string} - 待验证的邮箱地址
#### 返回值
- {boolean} - 验证通过返回 `true`，否则返回 `false`
#### 功能代码
```javascript
const emailRegex = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
function isEmail(value) {
if (typeof value !== 'string') return false;
return emailRegex.test(value);
}
```
#### 使用方法
```javascript
sinma.isEmail('user@example.com'); // true
sinma.isEmail('test@domain.co.uk'); // true
sinma.isEmail('invalid-email'); // false
sinma.isEmail('user@'); // false
```
#### 使用范例
```javascript
// 邮箱格式验证示例
function validateEmail(email) {
if (!email) {
return '邮箱地址不能为空';
}
if (!sinma.isEmail(email)) {
return '请输入正确的邮箱地址格式';
}
return null; // 验证通过
}
// 批量验证邮箱
const emails = ['user@test.com', 'invalid', 'admin@domain.org'];
const results = emails.map(email => ({
email,
valid: sinma.isEmail(email)
}));
console.log(results);
// [
// { email: 'user@test.com', valid: true },
// { email: 'invalid', valid: false },
// { email: 'admin@domain.org', valid: true }
// ]
```
---
### isIdCard(value, strict) - 身份证验证
验证中国大陆居民身份证号码。
#### 参数
- `value` {string} - 待验证的身份证号
- `strict` {boolean} - 是否启用严格验证模式，默认 `false`
#### 返回值
- {boolean} - 验证通过返回 `true`，否则返回 `false`
#### 功能代码
```javascript
const idCardRegex = /^[1-9]\d{5}(18|19|20)\d{2}((0[1-9])|(1[0-2]))(([0-2][1-9])|10|20|30|31)\d{3}[0-9Xx]$/;
function isIdCard(value, strict = false) {
if (typeof value !== 'string') return false;
if (!idCardRegex.test(value)) return false;
if (strict) {
return validateIdCard(value); // 严格验证包含校验位验证
}
return true;
}
```
#### 使用方法
```javascript
// 基础格式验证
sinma.isIdCard('110101199003070134'); // true
sinma.isIdCard('440301199001011234'); // true
sinma.isIdCard('12345'); // false
// 严格验证（包含校验位、省份代码、日期验证）
sinma.isIdCard('110101199003070134', true); // true
sinma.isIdCard('110101199003070133', true); // false（校验位错误）
```
#### 使用范例
```javascript
// 用户注册身份证验证
function validateUserIdCard(idCard) {
if (!idCard) {
return { valid: false, error: '身份证号不能为空' };
}
if (!sinma.isIdCard(idCard)) {
return { valid: false, error: '身份证号格式不正确' };
}
if (!sinma.isIdCard(idCard, true)) {
return { valid: false, error: '身份证号校验失败，请检查输入' };
}
// 提取身份证信息
const province = sinma.getProvinceByIdCard(idCard);
const birthday = sinma.getBirthDateByIdCard(idCard);
const gender = sinma.getGenderByIdCard(idCard);
return {
valid: true,
info: { province, birthday, gender }
};
}
const result = validateUserIdCard('110101199003070134');
console.log(result);
// {
// valid: true,
// info: {
// province: '北京',
// birthday: '1990-03-07',
// gender: '男'
// }
// }
```
---
### isEmpty(value) - 空值检测
检测值是否为空（null、undefined、空字符串、空数组、空对象）。
#### 参数
- `value` {*} - 待检测的值
#### 返回值
- {boolean} - 为空返回 `true`，否则返回 `false`
#### 功能代码
```javascript
function isEmpty(value) {
if (value == null) return true;
if (typeof value === 'string') return value.trim() === '';
if (Array.isArray(value)) return value.length === 0;
if (typeof value === 'object') return Object.keys(value).length === 0;
return false;
}
```
#### 使用方法
```javascript
sinma.isEmpty(null); // true
sinma.isEmpty(undefined); // true
sinma.isEmpty(''); // true
sinma.isEmpty(' '); // true
sinma.isEmpty([]); // true
sinma.isEmpty({}); // true
sinma.isEmpty('hello'); // false
sinma.isEmpty([1, 2]); // false
sinma.isEmpty({a: 1}); // false
```
#### 使用范例
```javascript
// 表单数据验证
function validateFormData(formData) {
const errors = [];
if (sinma.isEmpty(formData.name)) {
errors.push('姓名不能为空');
}
if (sinma.isEmpty(formData.email)) {
errors.push('邮箱不能为空');
}
if (sinma.isEmpty(formData.tags)) {
errors.push('至少选择一个标签');
}
return {
valid: errors.length === 0,
errors
};
}
// 过滤空值
const data = ['hello', '', null, 'world', undefined, 'test'];
const filtered = data.filter(item => !sinma.isEmpty(item));
console.log(filtered); // ['hello', 'world', 'test']
```
---
### isNumber(value) - 数字验证
判断值是否为有效数字类型。
#### 参数
- `value` {*} - 待验证的值
#### 返回值
- {boolean} - 是有效数字返回 `true`，否则返回 `false`
#### 功能代码
```javascript
function isNumber(value) {
return typeof value === 'number' && !isNaN(value);
}
```
#### 使用方法
```javascript
sinma.isNumber(123); // true
sinma.isNumber(0); // true
sinma.isNumber(-123); // true
sinma.isNumber(3.14); // true
sinma.isNumber('123'); // false
sinma.isNumber(NaN); // false
sinma.isNumber(Infinity); // true
```
#### 使用范例
```javascript
// 数值输入验证
function validateNumberInput(input) {
if (!sinma.isNumber(input)) {
return {
valid: false,
message: '请输入有效的数字'
};
}
if (input < 0) {
return {
valid: false,
message: '数字不能为负数'
};
}
return {
valid: true,
value: input
};
}
// 数组中数字过滤
const mixedArray = [1, '2', 3.14, 'hello', null, 42];
const numbers = mixedArray.filter(sinma.isNumber);
console.log(numbers); // [1, 3.14, 42]
```
---
### isChinese(value) - 中文字符验证
判断字符串是否全部为中文字符。
#### 参数
- `value` {string} - 待验证的字符串
#### 返回值
- {boolean} - 全部为中文字符返回 `true`，否则返回 `false`
#### 功能代码
```javascript
const chineseRegex = /^[\u4e00-\u9fa5]+$/;
function isChinese(value) {
if (typeof value !== 'string') return false;
return chineseRegex.test(value);
}
```
#### 使用方法
```javascript
sinma.isChinese('你好'); // true
sinma.isChinese('中文测试'); // true
sinma.isChinese('hello'); // false
sinma.isChinese('你好world'); // false
sinma.isChinese(''); // false
```
#### 使用范例
```javascript
// 中文姓名验证
function validateChineseName(name) {
if (!name) {
return { valid: false, error: '姓名不能为空' };
}
if (!sinma.isChinese(name)) {
return { valid: false, error: '请输入中文姓名' };
}
if (name.length < 2 || name.length > 4) {
return { valid: false, error: '姓名长度应为2-4个字符' };
}
return { valid: true };
}
// 文本内容过滤
function extractChineseText(text) {
return text.split('').filter(char => sinma.isChinese(char)).join('');
}
console.log(extractChineseText('Hello你好World世界123'));
// 输出: '你好世界'
```
---
### isUrl(value) - URL验证
验证URL地址格式是否正确。
#### 参数
- `value` {string} - 待验证的URL地址
#### 返回值
- {boolean} - 验证通过返回 `true`，否则返回 `false`
#### 功能代码
```javascript
const urlRegex = /^(https?:\/\/)?([\da-z.-]+)\.([a-z.]{2,6})([/\w .-]*)*\/?$/;
function isUrl(value) {
if (typeof value !== 'string') return false;
return urlRegex.test(value);
}
```
#### 使用方法
```javascript
sinma.isUrl('https://www.example.com'); // true
sinma.isUrl('http://test.co.uk'); // true
sinma.isUrl('www.google.com'); // true
sinma.isUrl('invalid-url'); // false
sinma.isUrl('ftp://example.com'); // false
```
#### 使用范例
```javascript
// 链接验证和格式化
function processUrl(url) {
if (!url) {
return { valid: false, error: 'URL不能为空' };
}
if (!sinma.isUrl(url)) {
return { valid: false, error: '请输入正确的URL格式' };
}
// 自动添加协议
const formattedUrl = url.startsWith('http') ? url : `https://${url}`;
return {
valid: true,
originalUrl: url,
formattedUrl: formattedUrl
};
}
const result = processUrl('www.example.com');
console.log(result);
// {
// valid: true,
// originalUrl: 'www.example.com',
// formattedUrl: 'https://www.example.com'
// }
```
## 综合示例
```javascript
// 用户注册表单验证
function validateRegistrationForm(formData) {
const errors = [];
// 验证手机号
if (!sinma.isPhone(formData.phone, true)) {
errors.push('请输入正确的手机号码');
}
// 验证邮箱
if (!sinma.isEmail(formData.email)) {
errors.push('请输入正确的邮箱地址');
}
// 验证身份证
if (!sinma.isIdCard(formData.idCard, true)) {
errors.push('请输入正确的身份证号码');
}
// 验证中文姓名
if (!sinma.isChinese(formData.name)) {
errors.push('请输入中文姓名');
}
// 验证个人网站（可选）
if (formData.website && !sinma.isUrl(formData.website)) {
errors.push('请输入正确的网站地址');
}
return {
valid: errors.length === 0,
errors: errors
};
}
// 使用示例
const userData = {
name: '张三',
phone: '13812345678',
email: 'zhangsan@example.com',
idCard: '110101199003070134',
website: 'www.zhangsan.com'
};
const validation = validateRegistrationForm(userData);
console.log(validation);
```
## 注意事项
1. **类型安全**: 所有验证函数都会先检查输入类型，非预期类型会返回 `false`
2. **性能优化**: 使用预编译的正则表达式，避免重复编译
3. **中文优化**: 专门针对中国大陆的数据格式进行优化
4. **严格模式**: 部分函数支持严格验证模式，提供更准确的验证结果
5. **向后兼容**: 保留旧版本API别名，如 `isPhonenum`、`isSfz` 等
## 相关模块
- [中文处理模块](./chinese.md) - 提供身份证信息提取等中文相关功能
- [字符串模块](./string.md) - 提供字符串处理和格式化功能
