react-native-masked-text CPF/CNPJ税号掩码详解:校验位算法如何保证号码真实有效

原创2026-10-11 13:39:52588 阅读

react-native-masked-text CPF/CNPJ税号掩码详解:校验位算法如何保证号码真实有效

react-native-masked-text 是一款纯 JavaScript 实现的 React Native 掩码文本输入组件,内置了 CPF(巴西个人税号)与 CNPJ(巴西企业税号)两种税号掩码,并内置完整的校验位算法,能在用户输入过程中实时格式化号码,并通过 isValid() 判断号码是否真实有效。本文将带新手快速看懂它的掩码格式、校验位计算原理,以及源码中每一处关键实现。

react-native-masked-text CPF/CNPJ税号掩码组件

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。

掩码与校验如何协作:整体架构一图读懂

整个流程可以概括为三步:

  1. 格式化:用户每次输入,getValue 把纯数字按掩码模式排版。CPF/CNPJ 都委托给 CustomMask 的 toPattern 逐字符对齐——遇到 9 放数字,遇到 .、-、/ 则自动补分隔符;
  2. 取原值:getRawValue 剥掉分隔符,得到纯数字串;
  3. 判真伪: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 校验位算法负责号码真实性。掌握了这套思路,你在做银行账号、手机号等其他带校验位的输入框时,也能轻松复制同样的模式。

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