鸿蒙三方库 | harmony-utils之RegexUtil正则匹配验证详解

前言

正则表达式是文本匹配和验证的强大工具，但编写和记忆正则模式并不容易。@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 安装依赖

bash 复制代码

ohpm install @pura/harmony-utils

2.2 邮箱验证

typescript 复制代码

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 手机号验证

typescript 复制代码

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;
    }
  })

三、完整页面示例

typescript 复制代码

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 表单综合校验

typescript 复制代码

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 自定义正则

typescript 复制代码

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

五、注意事项

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

六、常见问题

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

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

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

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

Q3: isUrl对IP地址有效吗？

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

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

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

总结

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

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