如何快速掌握 libphonenumber-js：轻量级 JavaScript 电话号码处理库完全指南

如何快速掌握 libphonenumber-js：轻量级 JavaScript 电话号码处理库完全指南

【免费下载链接】libphonenumber-js A simpler (and smaller) rewrite of Google Android's libphonenumber library in javascript 项目地址: https://gitcode.com/gh_mirrors/li/libphonenumber-js

libphonenumber-js 是一个轻量级的 JavaScript 库，专为电话号码解析、验证和格式化而设计。作为谷歌 Android 平台 libphonenumber 库的简化重写版本，它体积更小、性能更优，是前端和 Node.js 项目处理国际电话号码的理想选择。

📚 为什么选择 libphonenumber-js？

在全球化应用开发中，处理不同国家的电话号码格式常常令人头疼。libphonenumber-js 提供了一站式解决方案，支持：

• 🌍 国际电话号码解析与验证
• 📱 实时输入格式化（AsYouType）
• 🔍 文本中的电话号码智能提取
• 📊 多地区号码规则适配

核心优势：

• 轻量级：相比原版库体积减少 60%+
• 零依赖：纯 JavaScript 实现，无需额外依赖
• 模块化：提供 core/min/max 等多版本适配不同场景
• TypeScript 支持：完整类型定义文件确保类型安全

🚀 快速安装与基础使用

1. 安装步骤（3种方式任选）

npm 安装（推荐）

npm install libphonenumber-js --save

yarn 安装

yarn add libphonenumber-js

源码安装

git clone https://gitcode.com/gh_mirrors/li/libphonenumber-js
cd libphonenumber-js
npm install

2. 基础使用示例

解析国际电话号码

import { parsePhoneNumber } from 'libphonenumber-js';

const phoneNumber = parsePhoneNumber('+12133734253');
console.log(phoneNumber.formatInternational()); // +1 213-373-4253
console.log(phoneNumber.country); // US

验证号码有效性

import { isValidPhoneNumber } from 'libphonenumber-js';

console.log(isValidPhoneNumber('+12133734253', 'US')); // true
console.log(isValidPhoneNumber('123456789', 'CN')); // false

实时输入格式化

import { AsYouType } from 'libphonenumber-js';

const formatter = new AsYouType('US');
console.log(formatter.input('2133734253')); // (213) 373-4253

📦 版本选择指南

项目提供多个优化版本，可根据需求选择：

版本	特点	适用场景	体积
libphonenumber-js	完整功能	后端服务	~150KB
libphonenumber-js/min	精简版	移动端应用	~45KB
libphonenumber-js/mobile	最小化版	极端资源限制环境	~25KB

版本源码位置：max/（完整版）、min/（精简版）、mobile/（移动版）

💡 实用功能详解

文本中的号码提取

import { searchPhoneNumbersInText } from 'libphonenumber-js';

const text = '请联系我们：+12133734253 或发送邮件至support@example.com';
const numbers = searchPhoneNumbersInText(text, 'US');
console.log(numbers); // [{ number: '+12133734253', ... }]

获取号码类型

import { parsePhoneNumber } from 'libphonenumber-js';

const phoneNumber = parsePhoneNumber('+18001234567');
console.log(phoneNumber.getType()); // TOLL_FREE

🛠️ 高级配置与扩展

自定义元数据加载

对于特殊需求，可以手动加载不同版本的元数据：

import { parsePhoneNumber } from 'libphonenumber-js/core';
import metadata from 'libphonenumber-js/metadata.min.json';

const phoneNumber = parsePhoneNumber('+442079460958', metadata);

批量处理工具

项目提供批量处理工具，位于 source/tools/ 目录，支持：

• 号码格式批量转换
• 地区号码规则验证
• 元数据生成与优化

📝 项目结构解析

核心源码目录结构：

libphonenumber-js/
├── source/           # 核心源代码
│   ├── PhoneNumber.js      # 号码对象定义
│   ├── parsePhoneNumber.js # 解析逻辑
│   ├── AsYouType.js        # 实时格式化
│   └── metadata.js         # 号码规则元数据
├── test/             # 单元测试
├── max/              # 完整版本入口
├── min/              # 精简版本入口
└── mobile/           # 移动优化版本

🔍 常见问题解答

Q: 如何支持特定国家的号码格式？

A: 项目已内置全球200+国家/地区的号码规则，通过元数据文件 metadata.max.json 维护，位于项目根目录。

Q: 浏览器环境如何使用？

A: 可直接引入打包后的UMD文件：

<script src="libphonenumber-js/bundle/libphonenumber-js.min.js"></script>
<script>
  console.log(libphonenumber.isValidPhoneNumber('+12133734253'));
</script>

Q: 如何贡献代码？

A: 欢迎提交PR至官方仓库，所有核心逻辑位于 source/ 目录，测试用例请添加至 test/ 目录。

📈 性能优化建议

1. 按需导入：仅导入需要的功能减少 bundle 体积

   import { isValidPhoneNumber } from 'libphonenumber-js/min';
   

2. 元数据缓存：重复使用同一地区号码处理时缓存元数据

3. 避免实时解析：用户输入时使用防抖处理，减少解析频率

🎯 总结

libphonenumber-js 凭借其轻量、高效和易用的特性，已成为 JavaScript 生态中处理电话号码的首选库。无论你是开发全球化应用、构建表单验证，还是需要文本中的号码提取功能，它都能提供专业级的解决方案。

通过本文介绍的安装配置、基础使用和高级技巧，你已经掌握了这个强大工具的核心用法。立即将其集成到你的项目中，告别电话号码处理的烦恼吧！

官方文档：README.md
完整API参考：types.d.ts
示例代码：test/

【免费下载链接】libphonenumber-js A simpler (and smaller) rewrite of Google Android's libphonenumber library in javascript 项目地址: https://gitcode.com/gh_mirrors/li/libphonenumber-js