React Native输入掩码神器react-native-masked-text:让CPF、手机号、金额格式化变简单的完整介绍

原创2026-10-11 11:33:541,350 阅读

React Native输入掩码神器react-native-masked-text:让CPF、手机号、金额格式化变简单的完整介绍

react-native-masked-text 是一个纯 JavaScript 编写的 React Native 输入掩码组件库,只需一行代码就能让 CPF 税号、手机号、金额、信用卡等输入框自动格式化,还支持值校验与原始值获取,是移动端表单开发中处理"数字+符号"输入场景的实用工具。它不依赖任何原生模块,跨平台即装即用,适合新手快速上手。

react-native-masked-text 输入掩码组件横幅

一、什么是输入掩码(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 这样的格式。需要记住三点:

  1. type 必填,决定使用哪种掩码;
  2. options 可选,部分掩码(如 cel-phone、money)需要配置;
  3. 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 属性,格式化就完成了 ✨。

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