react-native-masked-text cel-phone手机号掩码实战:自动识别8位/9位号码与BRL国际格式

原创2026-10-11 18:09:561,947 阅读

react-native-masked-text cel-phone手机号掩码实战:自动识别8位/9位号码与BRL国际格式

react-native-masked-text 是一款面向 React Native 的纯 JavaScript 文本掩码组件库。本文带你实战其中的 cel-phone 手机号掩码:自动识别 8位/9位号码、支持 BRL 巴西本地格式与 INTERNATIONAL 国际格式,并演示如何用 getRawValue 提取纯数字。

react-native-masked-text 组件库标识图,内置 cel-phone 手机号掩码,支持 BRL 与国际号码格式化

为什么需要手机号输入掩码?📱

巴西手机号经历过一次「扩容」:早期号码是 8 位(8888-8888),后来新增了 9 位号段(98888-8888)。如果让用户手打格式,容易出现以下问题:

  • 位数混输:8 位与 9 位号码混在一起,格式错乱;
  • 地区码(DDD)位置尴尬:51、11 等区号该不该带括号、带几个空格,全靠用户自觉;
  • 提交数据不干净:接口要的是 51987654321 这样的纯数字,而界面显示的是 (51) 98765-4321。

cel-phone 掩码一次性解决这三个问题:用户只管敲数字,组件自动套格式、自动判断 8/9 位,取数时再还原纯数字。

cel-phone 手机号掩码快速上手

先安装依赖(要求 React Native 0.32.0 或更高版本):

npm install react-native-masked-text --save

基础用法只需三行配置:

import { TextInputMask } from 'react-native-masked-text'

<TextInputMask
  type={'cel-phone'}
  value={this.state.phone}
  onChangeText={text => this.setState({ phone: text })}
/>

不传 options 时,默认使用 BRL 格式并带 DDD,输入效果类似 (51) 98765-4321。组件会拦截 onChangeText 与 value,并自动把键盘切为数字键盘(numeric),无需额外设置。

自动识别 8位/9位号码的原理 🔍

核心逻辑在 cel-phone.mask.js 中,定义了三套掩码模板:

模板 值 适用场景
PHONE_8_MASK 9999-9999 传统 8 位号码
PHONE_9_MASK 99999-9999 新增 9 位号码
PHONE_INTERNATIONAL +999 999 999 999 国际格式

判断流程(见 cel-phone.mask.js):

  1. 先剔除输入中的所有非数字字符(包括用户粘贴的括号、空格);
  2. 如果启用了 withDDD,先去掉 DDD 占位的 2 位数字,看剩余位数;
  3. 剩余位数 ≥ 9 就切到 9 位掩码,否则保持 8 位掩码。

效果对照(来自 cel-phone.mask.test.js 的测试用例):

原始输入 掩码结果 说明
5188888888 (51) 8888-8888 8 位号码
51888888888 (51) 88888-8888 自动切换 9 位
(12) 1234-56789 (12) 12345-6789 粘贴带格式文本也能纠正

也就是说,即使用户从别处粘贴了一串乱格式号码,组件也会重新清洗并套用正确的掩码。

cel-phone 配置选项详解(maskType / withDDD / dddMask)⚙️

通过 options 可微调掩码行为:

参数 类型 默认值 说明
maskType string BRL BRL(巴西本地格式)或 INTERNATIONAL(国际格式)
withDDD boolean true 为 BRL 时是否包含 DDD 区号
dddMask string (99) 为 BRL 时 DDD 的格式模板

常见场景示例:

  • 3 位区号:把 dddMask 改成 '999 ',输入 12377777777 会显示 123 7777-7777;
  • 不带区号:设置 withDDD: false,输入 88888888 显示为 8888-8888,888888888 显示为 88888-8888;
  • 需要其他格式:改用 Custom 掩码自定义模板。
<TextInputMask
  type={'cel-phone'}
  options={{ maskType: 'BRL', withDDD: true, dddMask: '(99) ' }}
  value={this.state.phone}
  onChangeText={text => this.setState({ phone: text })}
/>

切换 INTERNATIONAL 国际手机号格式 🌐

如果业务面向海外用户,只需把 maskType 切为 INTERNATIONAL,掩码固定为 +999 999 999 999(4 位国家码 + 3 段号码):

<TextInputMask
  type={'cel-phone'}
  options={{ maskType: 'INTERNATIONAL' }}
  value={this.state.international}
  onChangeText={text => this.setState({ international: text })}
/>

注意:INTERNATIONAL 模式下 withDDD / dddMask 不再生效,因为模板是固定的。

getRawValue 获取纯数字与号码校验 ✅

界面显示的是掩码值,提交接口时通常需要纯数字。给组件挂一个 ref,调用 getRawValue() 即可:

<TextInputMask
  type={'cel-phone'}
  ref={ref => (this.phoneField = ref)}
  value={this.state.phone}
  onChangeText={text => this.setState({ phone: text })}
/>

// 掩码值:(51) 98765-4321
// 纯数字:51987654321
const unmasked = this.phoneField.getRawValue()

实现上就是复用基类的 removeNotNumbers,把非数字字符全部剥掉(见 _base.mask.js)。

💡 如果希望每次输入变化时同时拿到掩码值和原始值,可开启 includeRawValueInChangeText(1.12.0+),onChangeText 会收到 (maskedText, rawText) 两个参数,省去找 ref 的麻烦。

另外,不走组件也能用——静态的 MaskService 提供四个方法:toMask、toRawValue、isValid、getMask,适合在表单校验等场景直接调用,例如:

MaskService.toMask('cel-phone', '51987654321', { maskType: 'BRL' })
// => (51) 98765-4321

常见问题与排查 🛠️

  • babel 报 es2015 错误:执行 react-native start --reset-cache 清缓存即可;
  • 想换键盘类型:直接传 keyboardType 会覆盖掩码默认的 numeric 键盘,注意权衡;
  • 用户粘贴脏数据:不用担心,getValue 会先执行 removeNotNumbers 清洗,再套用掩码;
  • 校验是否输完:掩码内置 validate 方法(掩码值长度等于模板长度即为合法),也可通过 isValid() 在提交前拦截。

相关源码与文件速查 📂

文件 说明
lib/masks/cel-phone.mask.js cel-phone 掩码核心实现
lib/masks/_base.mask.js 掩码基类,提供数字清洗等通用能力
lib/mask-service.js 静态工具类 MaskService
lib/text-input-mask.js TextInputMask 输入组件
tests/mask/cel-phone.mask.test.js cel-phone 掩码测试用例
README.md 全部掩码类型的使用文档

一句话总结:cel-phone 掩码用「清洗数字 → 判断位数 → 套用模板」三步,把 8/9 位号码识别、BRL 与国际格式切换、纯数字提取这些琐碎但易错的工作全部收敛到一个组件里,是 React Native 表单场景里性价比极高的输入格式化方案。

登录后查看全文
react-native-masked-text