React Native输入掩码神器react-native-masked-text:让CPF、手机号、金额格式化变简单的完整介绍
React Native输入掩码神器react-native-masked-text:让CPF、手机号、金额格式化变简单的完整介绍
react-native-masked-text 是一个纯 JavaScript 编写的 React Native 输入掩码组件库,只需一行代码就能让 CPF 税号、手机号、金额、信用卡等输入框自动格式化,还支持值校验与原始值获取,是移动端表单开发中处理"数字+符号"输入场景的实用工具。它不依赖任何原生模块,跨平台即装即用,适合新手快速上手。
一、什么是输入掩码(Mask)?
想象一下这个场景:用户输入 CPF 税号时,希望输入到第 3 位后自动出现点号、第 9 位后自动出现短横线,最终显示成 123.456.789-01。传统做法需要手写一堆 onFocus / onChange 监听和字符串拼接,既繁琐又容易出 bug。
输入掩码组件做的事情就是:
- 🔢 实时格式化:用户每敲一个字符,输入框自动按规则插入分隔符;
- 🚫 过滤非法输入:字母进不进数字框,空格进不进税号框;
- ✅ 校验合法性:判断填写完整的 CPF、日期是否为真实有效值;
- 📤 还原原始值:把
123.456.789-01还原为纯数字12345678901,方便提交后端。
react-native-masked-text 基于纯 JS 实现(内部依赖 vanilla-masker.js 做掩码引擎),要求 React Native 0.32.0 及以上版本。
二、快速安装:一条命令搞定
在项目根目录执行:
npm install react-native-masked-text --save
如果需要查看源码,可克隆仓库:
git clone https://gitcode.com/gh_mirrors/re/react-native-masked-text
安装完成后,通过 import { TextInputMask } from 'react-native-masked-text' 即可使用,核心入口见 rnmt.js 与类型定义 index.d.ts。
三、内置 9 种掩码,覆盖绝大多数业务场景
组件内置的掩码定义在 lib/masks/index.js 中,共 9 种类型,通过 type 属性切换:
| type 值 | 用途 | 显示效果示例 |
|---|---|---|
cpf |
巴西个人税号 | 999.999.999-99 |
cnpj |
巴西企业税号 | 99.999.999/9999-99 |
cel-phone |
手机号(自动识别 10/11 位) | (99) 9999-9999 |
credit-card |
信用卡号(Visa/Master/Amex/Diners) | 9999 9999 9999 9999 |
money |
金额(货币符号、千分位可定制) | R$ 1.234,56 |
datetime |
日期时间(格式可配置) | DD/MM/YYYY HH:mm:ss |
zip-code |
邮编 | 99999-999 |
only-numbers |
仅允许数字 | 123456 |
custom |
自定义模式(9数字 / A字母 / S字母数字 / *任意非空格) |
由你定义 |
每种掩码的实现与测试分别在 lib/masks/ 和 tests/mask/ 目录下,比如 CPF 的实现在 cpf.mask.js,对应的单测在 cpf.mask.test.js。
四、TextInputMask 基本用法:三行代码接入
核心组件 TextInputMask 的源码位于 lib/text-input-mask.js,它是对原生 TextInput 的封装,几乎所有原生属性都能透传。以最简单的 CPF 输入为例:
import { TextInputMask } from 'react-native-masked-text'
<TextInputMask
type={'cpf'}
value={this.state.cpf}
onChangeText={text => this.setState({ cpf: text })}
/>
用户输入时会自动得到 123.456.789-01 这样的格式。需要记住三点:
type必填,决定使用哪种掩码;options可选,部分掩码(如cel-phone、money)需要配置;value与onChangeText与原生TextInput完全一致,无缝替换。
手机号:自动识别座机格式
<TextInputMask
type={'cel-phone'}
options={{ maskType: 'BRL', withDDD: true, dddMask: '(99) ' }}
value={this.state.phone}
onChangeText={text => this.setState({ phone: text })}
/>
maskType 支持 BRL(巴西本地)和 INTERNATIONAL(国际格式)两种,10 位和 11 位号码会自动区分。
金额:货币符号与分隔符都能改
<TextInputMask
type={'money'}
options={{ precision: 2, separator: ',', delimiter: '.', unit: 'R$' }}
value={this.state.money}
onChangeText={text => this.setState({ money: text })}
/>
金额掩码还支持 suffixUnit(后缀)等配置,实现见 money.mask.js。
自定义掩码:用模式串表达任意规则
遇到内置类型覆盖不了的场景,就用 custom,通过模式串描述规则:
<TextInputMask
type={'custom'}
options={{ mask: '999 AAA SSS' }}
value={this.state.text}
onChangeText={text => this.setState({ text })}
/>
其中 9 只接受数字、A 只接受字母、S 接受字母数字、* 接受除空格外任意字符。还可以传 validator 函数做自定义校验,详见 custom.mask.js。
五、高级技巧:拿原始值、校验、拦截输入
1️⃣ getRawValue:获取去掉掩码的原始值
提交表单时通常要纯数字,通过 ref 调用 getRawValue() 即可:
const unmasked = this.cpfField.getRawValue()
// 掩码值 123.456.789-01 -> 原始值 12345678901
不同掩码的返回值类型略有差异:金额掩码返回 Number,日期掩码返回 moment 对象,信用卡掩码返回数字分组数组。
2️⃣ isValid:校验是否填完整且合法
CPF、CNPJ、datetime 等掩码都提供 isValid() 方法,返回布尔值:
const cpfIsValid = this.cpfField.isValid()
CPF/CNPJ 的校验还会验证校验位算法,而不只是"填满 14 位"。
3️⃣ includeRawValueInChangeText:每次变更同时拿原始值
1.12.0 起支持该属性,onChangeText 会收到两个参数:
<TextInputMask
type={'cpf'}
includeRawValueInChangeText={true}
onChangeText={(maskedText, rawText) => {
// maskedText: 123.456.789-01
// rawText: 12345678901
}}
/>
4️⃣ checkText:拦截用户的输入
通过 checkText(previous, next) 返回 false 可阻止某些字符被写入,适合做黑白名单逻辑。
六、TextMask 与 MaskService:不只是输入框
除输入框外,库还提供两个补充组件:
- TextMask(lib/text-mask.js):把同样一套掩码套在只读的
Text组件上。例如展示脱敏信用卡号4567 **** **** 1234,连options配置都与TextInputMask一致; - MaskService(lib/mask-service.js):纯函数式 API,不依赖 UI 组件,可在任何业务逻辑中使用,提供 4 个静态方法:
toMask(type, value, settings):格式化值,如把'123'变成US$ 1.23;toRawValue(type, maskedValue, settings):反格式化为原始值;isValid(type, value, settings):校验值与掩码是否匹配;getMask(type, value, settings):获取当前使用的掩码字符串。
七、目录结构导览
| 路径 | 说明 |
|---|---|
| lib/text-input-mask.js | TextInputMask 输入框组件主实现 |
| lib/text-mask.js | TextMask 只读文本组件 |
| lib/base-text-component.js | 两个组件的公共基类 |
| lib/mask-service.js | 无 UI 的掩码工具类 |
| lib/masks/ | 9 种内置掩码的具体实现 |
| lib/internal-dependencies/vanilla-masker.js | 内置的掩码解析引擎 |
| tests/mask/ | 各掩码的单元测试用例 |
| README.md | 官方完整文档(含全部示例代码) |
| CHANGELOG.md | 版本更新历史 |
八、常见问题排查 🛠️
Q:构建时报 es2015 相关错误?
运行 react-native start --reset-cache 重置 Babel 缓存即可。
Q:TextMask 显示的内容没有出现? 当值不符合掩码规则时,TextMask 不会渲染内容,这是预期行为。
Q:想换掉原生 TextInput 的样式?
使用 customTextInput + customTextInputProps 两个属性即可挂载任意自定义输入组件。
Q:项目还在维护吗? 作者已不再开发 JS 应用,仓库进入维护状态(见 README.md 中的 Alert 说明)。当前版本 1.13.0 功能完整稳定,日常表单场景完全够用;若遇到新需求可自行 Fork 扩展。
九、总结
react-native-masked-text 用"纯 JS、零原生依赖"的轻量方案,把 CPF、手机号、金额、信用卡、日期这些高频格式化场景做成了开箱即用的 type 配置,再辅以 isValid 校验、getRawValue 原始值提取和 custom 自定义掩码三板斧,足以覆盖绝大多数移动端的数字格式化需求。如果你是 React Native 新手,只需要记住一句话:把 TextInput 换成 TextInputMask 并加上 type 属性,格式化就完成了 ✨。
