这是什么?
Google 的通用 Java、C++ 和 JavaScript 库,用于解析、格式化和验证国际电话号码。 Java 版本针对智能手机的运行进行了优化,并从 4.0(Ice Cream Sandwich)开始被 Android 框架使用。
快速链接
- 报告问题?想要发送拉请求吗?请参阅贡献指南
- 查看常见问题
- 有趣!程序员对电话号码的误解
- 在你感兴趣的代码相关的目录中寻找 README。
- 对于贡献者和移植者:如何运行 Java 演示
- 对于移植者:如何修改元数据
功能亮点
- 解析、格式化和验证世界上所有国家/地区的电话号码。
- getNumberType -- 根据号码本身获取号码的类型;能够区分固定电话、移动电话、免费电话、高级费率、共享费用、VoIP、个人号码、UAN、寻呼机和语音邮件(只要可行)。
- isNumberMatch -- 获得两个号码是否相同的置信度。
- getExampleNumber 和 getExampleNumberForType -- 为所有国家/地区提供有效的示例号码,并可指定需要哪种类型的示例电话号码。
- isPossibleNumber -- 通过使用长度信息快速猜测一个号码是否是一个可能的电话号码,比完整验证快得多。
- isValidNumber -- 使用长度和前缀信息对一个区域的电话号码进行完全验证。
- AsYouTypeFormatter -- 当用户输入每个数字时,即时格式化电话号码。
- findNumbers -- 在文本中查找号码。
- PhoneNumberOfflineGeocoder -- 提供与电话号码相关的地理信息。
- PhoneNumberToCarrierMapper -- 提供与电话号码相关的运营商信息。
- PhoneNumberToTimeZonesMapper -- 提供与电话号码相关的时区信息。
演示
Java
在 GitHub 发布后,Java 演示 的更新略有延迟。
最后一次演示更新:v8.12.9。
如果这个数字低于最新版本的版本号码,则说明我们处于两个版本之间,演示可能处于其中一个版本。
JavaScript
JavaScript 演示 可以在不同的标签下运行;这个链接将带您到 master 。【由于 RawGit 已被废弃,JS 演示链接无法使用。】TODO 在其他平台上托管。
Java代码
要在你的应用程序中包含 Java 代码,可以与 Maven 集成(请参阅 wiki ),或者从 Maven 仓库 下载最新的 jar 包。
Javadoc
Javadoc 会自动更新以反映最新的版本,网址为 http://javadoc.io/doc/com.googlecode.libphonenumber/libphonenumber/。
版本控制和公告
我们通常会根据这些准则来选择版本号。
如果自上一个版本以来推送到主版本的任何变化与现有 libphonenumber API 的约定/规范不兼容,或者可能导致 libphonenumber(Java、C++ 或 JS)客户端不得不修改他们的代码来继续构建,我们就会发布一个主要版本。例如,如果上一个版本是 7.7.3,新的版本就是 8.0.0。
如果这些变化使客户端能够更新他们的代码以利用新的功能,并且如果客户端不得不在该版本被标记为 "bad" 的情况下回滚这些变化,我们将发布一个次要版本。例如,我们会从 7.7.3 到 7.8.0。
否则,包括仅当版本包含
元数据 变化时,我们会发布次小版本,例如 7.7.3 至 7.7.4。
有时, 我们会对代码或元数据进行内部修改, 虽然这些修改不会影响到客户端的兼容性, 但却会影响到库的移植者的兼容性。对于这样的改动,我们会在 libphonenumber-discUSS 中发布公告。这样的改动不会反映在版本号中,如果没有其他改动,我们会发布一个次小版本。
想得到新版本的通知吗?在一年中的大部分时间里,除了节假日和情有可原的情况,我们每两周发布一次。我们会更新发布标签并记录详细的发布说明。我们也会在每次发布时向 libphonenumber-discuss 发送公告 -- 讨论每个版本。
快速示例
假设你有一个代表瑞士电话号码的字符串。这就是你如何将它解析/归一化为一个 PhoneNumber 对象的方式:
String swissNumberStr = "044 668 18 00"; PhoneNumberUtil phoneUtil = PhoneNumberUtil.getInstance(); try { PhoneNumber swissNumberProto = phoneUtil.parse(swissNumberStr, "CH"); } catch (NumberParseException e) { System.err.println("NumberParseException was thrown: " + e.toString()); }
此时, swissNumberProto 包含:
{ “country_code”:41, “national_number”:446681800 }
PhoneNumber 是一个最初由 phonenumber.proto 自动生成的类,为了提高效率,它做了必要的修改。关于每个字段的详细含义,请参考 resources/phonenumber.proto。 现在让我们验证一下这个号码是否有效:
boolean isValid = phoneUtil.isValidNumber(swissNumberProto); //returns true
格式化方法支持的格式有几种,如下所示:
//Produces "+41 44 668 18 00" System.out.println(phoneUtil.format(swissNumberProto, PhoneNumberFormat.INTERNATIONAL)); //Produces "044 668 18 00" System.out.println(phoneUtil.format(swissNumberProto, PhoneNumberFormat.NATIONAL)); //Produces "+41446681800" System.out.println(phoneUtil.format(swissNumberProto, PhoneNumberFormat.E164));
您还可以选择按照从其他国家/地区拨打的方式格式化数字:
//Produces "011 41 44 668 1800", the number when it is dialed in the United States. System.out.println(phoneUtil.formatOutOfCountryCallingNumber(swissNumberProto, "US"));
输入电话号码时的格式化
PhoneNumberUtil phoneUtil = PhoneNumberUtil.getInstance(); AsYouTypeFormatter formatter = phoneUtil.getAsYouTypeFormatter("US"); System.out.println(formatter.inputDigit('6')); //Outputs "6" ... //Input more digits System.out.println(formatter.inputDigit('3')); //Now outputs "650 253"
电话号码的地理编码
PhoneNumberOfflineGeocoder geocoder = PhoneNumberOfflineGeocoder.getInstance(); //Outputs "Zurich" System.out.println(geocoder.getDescriptionForNumber(swissNumberProto, Locale.ENGLISH)); //Outputs "Zürich" System.out.println(geocoder.getDescriptionForNumber(swissNumberProto, Locale.GERMAN)); //Outputs "Zurigo" System.out.println(geocoder.getDescriptionForNumber(swissNumberProto, Locale.ITALIAN));
将电话号码映射到原运营商
警告:我们不提供有关电话号码的当前运营商的数据,只提供分配到相应范围的原运营商的数据。阅读关于号码可携性的内容。了解号码可携性的内容。
PhoneNumber swissMobileNumber = new PhoneNumber().setCountryCode(41).setNationalNumber(798765432L); PhoneNumberToCarrierMapper carrierMapper = PhoneNumberToCarrierMapper.getInstance(); //Outputs "Swisscom" System.out.println(carrierMapper.getNameForNumber(swissMobileNumber, Locale.ENGLISH));
有关如何使用该库的更多示例,可以在单元测试中找到。
第三方移植
我们知道有几个电话号码库的第三方移植库。我们在这里分享他们,是因为他们或许对开发者有用。
不过,我们强调这些移植是由 libphonenumber 项目之外的开发者完成的。我们不评估它们的质量,也不影响它们的维护过程。
- C#: https://github.com/twcclegg/libphonenumber-csharp
- Objective-c: https://github.com/iziz/libPhoneNumber-iOS
- PHP: https://github.com/giggsey/libphonenumber-for-php
- PostgreSQL数据库类型: https://github.com/blm768/pg-libphonenumber
- Python: https://github.com/daviddrysdale/python-phonenumbers
- Ruby: https://github.com/mobi/telephone_number
- Rust: https://github.com/1aim/rust-phonenumber
我们自己版本的替代品:
- Android-optimized:我们的 Java 版本从 Class#getResourcesAsStream 加载元数据,并要求 Android 应用程序遵循 Android 加载的最佳实践,即重新打包元数据并自己从 AssetManager#open() 加载(常见问题)。如果您不想这样做,请查看 https://github.com/MichaelRocks/libphonenumber-android 的移植版,它会重新打包元数据并使用 AssetManager#open(),并且可以依赖它,而不需要客户端进行那些特定的加载优化。
- Javascript:如果你不想使用我们的版本,因为它依赖于Closure,还有其他一些选择,其中包括 https://github.com/halt-hammerzeit/libphonenumber-js -- 一个简约的重写,大小约 110 KB;以及 https://github.com/seegno/google-libphonenumber -- 一个可通过 npm 安装的原版未修改库的浏览器兼容包装器,它打包了 Google Closure 库,大小约 420 KB。
(Second edition: vz revised at 2020.08.30)