react-native-masked-text cel-phone手机号掩码实战:自动识别8位/9位号码与BRL国际格式
react-native-masked-text cel-phone手机号掩码实战:自动识别8位/9位号码与BRL国际格式
react-native-masked-text 是一款面向 React Native 的纯 JavaScript 文本掩码组件库。本文带你实战其中的 cel-phone 手机号掩码:自动识别 8位/9位号码、支持 BRL 巴西本地格式与 INTERNATIONAL 国际格式,并演示如何用 getRawValue 提取纯数字。
为什么需要手机号输入掩码?📱
巴西手机号经历过一次「扩容」:早期号码是 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):
- 先剔除输入中的所有非数字字符(包括用户粘贴的括号、空格);
- 如果启用了
withDDD,先去掉 DDD 占位的 2 位数字,看剩余位数; - 剩余位数 ≥ 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 表单场景里性价比极高的输入格式化方案。
