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 库，为开发者提供了简单易用的电话号码处理方案。

项目概述

libphonenumber-js 是一个功能完整的电话号码处理库，主要特点包括：

• 轻量级设计：完整包大小仅 145 kB，相比原版 550 kB 大幅优化
• TypeScript 支持：内置完整的类型定义
• 全功能覆盖：支持解析、格式化、验证等多种操作
• 现代化架构：支持 ES6 模块和 CommonJS 两种导入方式

安装与集成

npm 安装

npm install libphonenumber-js --save

yarn 安装

yarn add libphonenumber-js

快速开始

// ES6 模块导入
import parsePhoneNumber from 'libphonenumber-js'

// 解析电话号码
const phoneNumber = parsePhoneNumber(' 8 (800) 555-35-35 ', 'RU')

if (phoneNumber) {
  console.log(phoneNumber.country) // 'RU'
  console.log(phoneNumber.number) // '+78005553535'
  console.log(phoneNumber.isPossible()) // true
  console.log(phoneNumber.isValid()) // true
}

核心功能详解

电话号码解析

parsePhoneNumber() 函数是库的核心功能，能够从字符串中提取完整的电话号码信息：

import parsePhoneNumber from 'libphonenumber-js'

const phoneNumber = parsePhoneNumber('+12133734253')

if (phoneNumber) {
  console.log(phoneNumber.formatInternational()) // '+1 213 373 4253'
  console.log(phoneNumber.formatNational()) // '(213) 373-4253'
  console.log(phoneNumber.getURI()) // 'tel:+12133734253'
}

电话号码格式化

libphonenumber-js 提供多种格式化选项：

import parsePhoneNumber from 'libphonenumber-js'

const phoneNumber = parsePhoneNumber('+12133734253')

if (phoneNumber) {
  // 国际格式
  phoneNumber.formatInternational() // '+1 213 373 4253'
  
  // 国内格式
  phoneNumber.formatNational() // '(213) 373-4253'
  
  // URI 格式
  phoneNumber.getURI() // 'tel:+12133734253'
}

实时输入格式化

"As You Type" 功能让用户在输入时就能看到格式化的结果：

import { AsYouType } from 'libphonenumber-js'

const formatter = new AsYouType()
formatter.input('+12133734') // 返回: '+1 213 373 4'

// 指定默认国家
const formatterUS = new AsYouType('US')
formatterUS.input('2133734') // 返回: '(213) 373-4'

电话号码验证

验证电话号码的有效性：

import {
  isPossiblePhoneNumber,
  isValidPhoneNumber,
  validatePhoneNumberLength
} from 'libphonenumber-js'

// 基本验证
isPossiblePhoneNumber('8 (800) 555-35-35', 'RU') // true
isValidPhoneNumber('8 (800) 555-35-35', 'RU') // true

// 详细验证
validatePhoneNumberLength('8 (800) 555', 'RU') // 'TOO_SHORT'
validatePhoneNumberLength('8 (800) 555-35-35', 'RU') // undefined (长度有效)

文本中搜索电话号码

在长文本中查找所有电话号码：

import { findPhoneNumbersInText } from 'libphonenumber-js'

const text = `
  For tech support call +7 (800) 555-35-35 internationally
  or reach a local US branch at (213) 373-4253 ext. 1234.
`

const results = findPhoneNumbersInText(text, 'US')
// 返回包含所有找到的电话号码及其位置信息的数组

元数据配置策略

libphonenumber-js 提供四种不同的元数据配置，以适应不同的使用场景：

min 配置（默认）

• 大小：约 80 kB
• 适用场景：仅需验证电话号码长度，不需要严格验证数字或获取号码类型

max 配置

• 大小：约 145 kB
• 适用场景：需要严格验证电话号码数字或获取号码类型

mobile 配置

• 大小：约 95 kB
• 适用场景：仅处理移动电话号码

core 配置

• 自定义元数据，适用于需要极致优化的场景

导入方式选择

根据需求选择合适的导入路径：

// 默认 min 配置
import parsePhoneNumber from 'libphonenumber-js'

// max 配置
import parsePhoneNumber from 'libphonenumber-js/max'

// mobile 配置  
import parsePhoneNumber from 'libphonenumber-js/mobile'

// core 配置（无预置元数据）
import parsePhoneNumber from 'libphonenumber-js/core'

实际应用示例

表单验证场景

import { isValidPhoneNumber } from 'libphonenumber-js'

function validatePhoneInput(phoneNumber, countryCode) {
  return isValidPhoneNumber(phoneNumber, countryCode)
}

// 使用示例
const isValid = validatePhoneInput('+1 213 373 4253', 'US')

用户界面集成

import { AsYouType } from 'libphonenumber-js'

class PhoneInput extends React.Component {
  constructor(props) {
    super(props)
    this.formatter = new AsYouType(props.defaultCountry)
  }
  
  handleChange = (event) => {
    const formattedValue = this.formatter.input(event.target.value)
    this.props.onChange(formattedValue)
  }
}

最佳实践建议

1. 选择合适的元数据配置：根据应用需求在性能和功能间取得平衡

2. 始终指定默认国家：提高解析准确性和性能

3. 合理使用验证函数：根据场景选择 isPossiblePhoneNumber 或 isValidPhoneNumber

4. 处理边界情况：电话号码解析可能返回 null，需要进行空值检查

5. 考虑国际化：支持多种国家代码和电话号码格式

libphonenumber-js 作为专业的电话号码处理工具，能够帮助开发者快速实现电话号码的解析、格式化和验证功能，是现代 Web 应用中不可或缺的工具之一。

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