前言

正则表达式是文本匹配和验证的强大工具，但编写和记忆正则模式并不容易。@pura/harmony-utils 的 RegexUtil 封装了常用正则验证方法，开发者无需手写正则即可完成常见验证。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、RegexUtil核心API

RegexUtil 提供了以下正则验证方法：

方法	说明	返回类型	使用场景
isEmail(str)	是否邮箱	boolean	邮箱校验
isPhone(str)	是否手机号	boolean	手机号校验
isUrl(str)	是否URL	boolean	链接校验
isIdCard(str)	是否身份证号	boolean	身份验证
isChinese(str)	是否纯中文	boolean	中文检查
isNumber(str)	是否纯数字	boolean	数字检查
matches(str, regex)	自定义正则匹配	boolean	自定义验证

1.1 核心特性

• 简洁易用：封装复杂正则为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 常用覆盖：覆盖邮箱、手机号、URL、身份证等常见验证

1.2 验证方法对照

方法	有效示例	无效示例	说明
isEmail	test@qq.com	test@	邮箱格式
isPhone	13800138000	12345	11位手机号
isUrl	https://a.com	abc	URL格式
isIdCard	110101199001011234	12345	18位身份证

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 邮箱验证

import { RegexUtil } from '@pura/harmony-utils';

Button('邮箱验证')
  .width('100%')
  .onClick(() => {
    try {
      let r1 = RegexUtil.isEmail('test@example.com');
      let r2 = RegexUtil.isEmail('invalid-email');
      this.result = `test@example.com: ${r1 ? '有效 ✅' : '无效 ❌'}\ninvalid-email: ${r2 ? '有效 ✅' : '无效 ❌'}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 手机号验证

Button('手机号验证')
  .width('100%')
  .onClick(() => {
    try {
      let r1 = RegexUtil.isPhone('13800138000');
      let r2 = RegexUtil.isPhone('12345');
      this.result = `13800138000: ${r1 ? '有效 ✅' : '无效 ❌'}\n12345: ${r2 ? '有效 ✅' : '无效 ❌'}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

import { RegexUtil, ToastUtil } from '@pura/harmony-utils';

@Entry
@Component
struct RegexDemo {
  @State result: string = '';
  @State input: string = '';

  build() {
    Column({ space: 12 }) {
      TextInput({ text: this.input }).onChange(v => this.input = v)
      Button('验证邮箱').width('100%').onClick(() => {
        this.result = `邮箱: ${RegexUtil.isEmail(this.input) ? '有效 ✅' : '无效 ❌'}`;
      });
      Button('验证手机号').width('100%').onClick(() => {
        this.result = `手机号: ${RegexUtil.isPhone(this.input) ? '有效 ✅' : '无效 ❌'}`;
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 表单综合校验

import { RegexUtil, ToastUtil } from '@pura/harmony-utils';

function validateRegisterForm(email: string, phone: string): boolean {
  if (!RegexUtil.isEmail(email)) {
    ToastUtil.show('邮箱格式不正确');
    return false;
  }
  if (!RegexUtil.isPhone(phone)) {
    ToastUtil.show('手机号格式不正确');
    return false;
  }
  return true;
}

4.2 自定义正则

function isPostalCode(str: string): boolean {
  return RegexUtil.matches(str, /^\d{6}$/);
}

五、注意事项

1. 手机号规则：isPhone基于中国大陆手机号规则
2. 身份证校验：isIdCard仅校验格式，不验证真实性
3. URL协议：isUrl通常要求包含协议前缀
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 正则性能：复杂正则可能影响性能

六、常见问题

Q1: isPhone支持国际手机号吗？

默认仅支持中国大陆手机号，国际号码需自定义正则。

Q2: isIdCard支持15位身份证吗？

取决于实现，通常支持18位新版身份证。

Q3: isUrl对IP地址有效吗？

通常有效，如 http://192.168.1.1 会被识别为URL。

Q4: 如何添加自定义验证规则？

使用matches方法传入自定义正则表达式即可。

总结

RegexUtil 的正则验证方法为表单校验提供了便捷支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以利用这些方法快速实现邮箱、手机号等常见验证。

本文基于 @pura/harmony-utils 工具库，更多功能请参考官方文档与后续系列文章。