react-native-masked-text CPF/CNPJ税号掩码详解:校验位算法如何保证号码真实有效
react-native-masked-text CPF/CNPJ税号掩码详解:校验位算法如何保证号码真实有效
react-native-masked-text 是一款纯 JavaScript 实现的 React Native 掩码文本输入组件,内置了 CPF(巴西个人税号)与 CNPJ(巴西企业税号)两种税号掩码,并内置完整的校验位算法,能在用户输入过程中实时格式化号码,并通过 isValid() 判断号码是否真实有效。本文将带新手快速看懂它的掩码格式、校验位计算原理,以及源码中每一处关键实现。
CPF 和 CNPJ 是什么?巴西税号结构一文看懂
CPF(Cadastro de Pessoas Físicas)是巴西个人税号,CNPJ(Cadastro Nacional da Pessoa Jurídica)是巴西企业税号。两者的结构都固定,最后两位是"校验位"——由前面的数字按特定算法算出来的,只要错一位就能被发现。
| 税号类型 | 位数 | 掩码格式 | 示例 |
|---|---|---|---|
| CPF(个人) | 11 位 | 999.999.999-99 |
078.338.236-78 |
| CNPJ(企业) | 14 位 | 99.999.999/9999-99 |
79.885.262/0001-30 |
掩码里的 9 代表"此处填一个数字",.、/、- 是自动补齐的固定分隔符。也就是说,用户只需输入纯数字,组件会自动补全格式。
在 React Native 中如何添加 CPF/CNPJ 税号格式化输入
使用非常简单:给 <TextInputMask> 组件指定 type 为 cpf 或 cnpj 即可。组件内部由 mask-resolver.js 根据类型自动匹配到对应的掩码类(如 cpf.mask.js、cnpj.mask.js),这些掩码统一注册在 masks/index.js 中。
<TextInputMask
type={'cpf'}
value={this.state.cpf}
onChangeText={text => this.setState({ cpf: text })}
ref={(ref) => this.cpfField = ref}
/>
// 提交前校验号码是否有效
const cpfIsValid = this.cpfField.isValid() // 返回 boolean
const unmasked = this.cpfField.getRawValue() // 返回 12345678901 这样的纯数字
isValid():调用掩码的validate方法,即下文的校验位算法;getRawValue():基于 BaseMask 的removeNotNumbers能力,剔除所有非数字字符,得到"去掩码"原始值。
这样设计的好处:界面负责好看(带分隔符),存储和提交负责干净(纯数字),校验负责可靠(校验位算法),三者各司其职。
CPF 校验位算法:加权求和 + 模 11 运算
CPF 校验的核心思路是:用降序权重对前几位数字加权求和,再取模 11,结果必须与第 10、11 位(校验位)一致。算法实现在 validateCPF 中。
第一步:计算第 1 个校验位(第 10 位)
取前 9 位数字,分别乘以权重 10、9、8、…、2(源码中写作 11 - i):
sum = 0×10 + 7×9 + 8×8 + 3×7 + 3×6 + 8×5 + 2×4 + 3×3 + 6×2 = 235
rest = (sum × 10) % 11 = 2350 % 11 = 7
结果 7 必须等于第 10 位。
第二步:计算第 2 个校验位(第 11 位)
把第 10 位也纳入,前 10 位乘以权重 11、10、…、2:
sum = 0×11 + 7×10 + 8×9 + 3×8 + 3×7 + 8×6 + 2×5 + 3×4 + 6×3 + 7×2 = 289
rest = (289 × 10) % 11 = 2890 % 11 = 8
结果 8 必须等于第 11 位。两个校验位都通过,号码才算有效。对应源码见 cpf.mask.js 第 35-62 行。
额外规则:拒绝"连号"号码
00000000000 到 99999999999 这类所有位都相同的号码即使数学上通过也会被直接判为无效(见 cpf.mask.js 第 19-33 行),这是巴西法规对 CPF 的硬性要求。
🧪 以上逻辑的完整测试用例可参考 cpf.mask.test.js:例如 07833823678 校验通过,而 11111111111 即使格式正确也会被判为无效。
CNPJ 校验位算法:14 位号码的双重校验
CNPJ 的校验位在 validateCnpj 中实现,核心是一张固定的权重表:
[6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2]
- 第 1 个校验位:前 12 位数字从权重表的第 2 个权重(5)开始依次相乘求和;
- 第 2 个校验位:前 13 位(含第 1 个校验位)从权重表的第 1 个权重(6)开始依次相乘求和。
求和后的处理规则是:对 11 取余,余数小于 2 则校验位为 0,否则校验位 = 11 - 余数。
以测试用例 79.885.262/0001-30 为例验证第 1 个校验位:
sum = 7×5 + 9×4 + 8×3 + 8×2 + 5×9 + 2×8 + 6×7 + 2×6 + 0×5 + 0×4 + 0×3 + 1×2 = 228
228 % 11 = 8(不小于 2)→ 校验位 = 11 - 8 = 3 ✅
第 2 个校验位同理,加权求和为 242,242 % 11 = 0(小于 2),所以校验位是 0 ✅。两位都吻合,号码有效。
⚠️ 对比可以发现两种税号的微妙差异:CPF 用 (sum × 10) % 11 且结果 ≥ 10 时归零;CNPJ 直接取余后"小于 2 归零、否则 11 减余数"。原理同源(都是模 11 校验),细节不同——这正是需要对照源码学习的原因。测试用例见 cnpj.mask.test.js。
掩码与校验如何协作:整体架构一图读懂
整个流程可以概括为三步:
- 格式化:用户每次输入,
getValue把纯数字按掩码模式排版。CPF/CNPJ 都委托给 CustomMask 的toPattern逐字符对齐——遇到9放数字,遇到.、-、/则自动补分隔符; - 取原值:
getRawValue剥掉分隔符,得到纯数字串; - 判真伪:
validate先拒绝空值,再交给校验位算法,只有数学上成立的号码才返回true。
| 方法 | 作用 | 位置 |
|---|---|---|
getType() |
返回 cpf / cnpj,供 MaskResolver 路由 |
mask-resolver.js |
getValue() |
数字串 → 带掩码的显示格式 | cpf.mask.js |
getRawValue() |
带掩码格式 → 纯数字 | cnpj.mask.js |
validate() |
校验位算法判真伪 | cpf.mask.js |
快速上手:克隆仓库动手验证
想亲手跑一遍校验位算法,可以克隆仓库查看源码与测试:
git clone https://gitcode.com/gh_mirrors/re/react-native-masked-text
进入 __tests__/mask/ 目录,重点阅读 cpf.mask.test.js 和 cnpj.mask.test.js,把文中的手工计算与测试断言一一对照,就能彻底吃透 CPF/CNPJ 税号掩码的校验位机制。
📌 小结:react-native-masked-text 把"格式美观"和"数据可信"分离处理——掩码负责输入体验,模 11 校验位算法负责号码真实性。掌握了这套思路,你在做银行账号、手机号等其他带校验位的输入框时,也能轻松复制同样的模式。
