google/libphonenumber
GitHub: google/libphonenumber
Google开发的多语言电话号码处理库，提供全球电话号码的解析、验证、格式化及地理编码等功能。
Stars: 18001 | Forks: 2154
# 它是什么？
Google 的通用 Java、C++ 和 JavaScript 库，用于解析、格式化和验证国际电话号码。Java 版本经过优化，适用于智能手机，并自 Android 4.0（Ice Cream Sandwich）起被 Android 框架使用。
# 快速链接
* **想要报告问题？** 想要发送 pull request？请参阅[贡献指南](CONTRIBUTING.md)
* 查看[常见问题](FAQ.md)
* 有趣！[程序员关于电话号码的错误认知](FALSEHOODS.md)
* 在与您感兴趣的代码相关的目录中查找
[`README`](https://github.com/google/libphonenumber/find/master)。
* 面向贡献者和移植者：[如何运行 Java demo](run-java-demo.md)
* 面向移植者：[如何进行元数据更改](making-metadata-changes.md)
# 功能亮点
* 解析、格式化和验证世界上所有国家/地区的电话号码。
* `getNumberType` - 根据号码本身获取号码类型；能够区分固定电话、移动电话、免费电话、Premium Rate、Shared Cost、VoIP、个人号码、UAN、寻呼机和语音邮件（只要可行）。
* `isNumberMatch` - 获取关于两个号码是否可能相同的置信度。
* `getExampleNumber` 和 `getExampleNumberForType` - 为所有国家/地区提供有效的示例号码，并可选择指定所需示例电话号码的类型。
* `isPossibleNumber` - 仅使用长度信息快速猜测号码是否可能是电话号码，比完整验证快得多。
* `isValidNumber` - 使用长度和前缀信息对某个区域的电话号码进行完整验证。
* `AsYouTypeFormatter` - 在用户输入每位数字时即时格式化电话号码。
* `findNumbers` - 在文本中查找号码。
* `PhoneNumberOfflineGeocoder` - 提供与电话号码相关的地理信息。
* `PhoneNumberToCarrierMapper` - 提供与电话号码相关的运营商信息。
* `PhoneNumberToTimeZonesMapper` - 提供与电话号码相关的时区信息。
# Demo
## Java
[Java demo](https://libphonenumber.appspot.com/) 会在 GitHub 发布后稍有延迟地进行更新。
上次 demo 更新：v9.0.30。
注意：尽管库（主分支/[maven release](https://repo1.maven.org/maven2/com/googlecode/libphonenumber/libphonenumber/8.12.56/)）的版本为 v8.12.57，但由于一些部署问题，我们无法使用新的二进制版本更新 Java demo。我们将很快解决此问题。同时，请使用 JS demo。
如果此数字低于[最新发布版本的版本号](https://github.com/google/libphonenumber/releases)，说明我们正处于两次发布之间，demo 可能是其中任何一个版本。
### Demo App
此存储库中有一个名为 [E.164 Formatter](java/demoapp) 的 Android Demo App。此 App 的目的是展示如何在真实场景中使用该库的示例，特别是针对使用 Java 的 Android App。
## JavaScript
[JavaScript demo](https://htmlpreview.github.io/?https://github.com/google/libphonenumber/blob/master/javascript/i18n/phonenumbers/demo-compiled.html) 可以在各种标签下运行；此链接会将您带到 `master` 分支。
# Java 代码
要在您的应用程序中包含 Java 代码，可以通过 Maven 进行集成（参见 [wiki](https://github.com/google/libphonenumber/wiki)）或从 [Maven repository](https://repo1.maven.org/maven2/com/googlecode/libphonenumber/libphonenumber/) 下载最新的 jar 包。
# Javadoc
Javadoc 会自动更新以反映最新版本，网址为
https://javadoc.io/doc/com.googlecode.libphonenumber/libphonenumber/。
# 版本控制与公告
我们通常遵循以下指南来选择发布版本号。
如果自上次发布以来推送到 master 的任何更改与现有 libphonenumber API 的意图/规范不兼容，或者可能导致 libphonenumber（Java、C++ 或 JS）客户端不得不更改其代码以保持构建成功，我们将发布一个主要版本。例如，如果上次发布是 7.7.3，新版本将是 8.0.0。
如果这些更改中的任何一个*使*客户端能够更新其代码以利用新功能，并且如果客户端在发布被标记为“bad”时必须回滚这些更改，我们将发布一个次要版本。例如，我们将从 7.7.3 更新到 7.8.0。
否则，包括发布仅包含[元数据](FAQ.md#metadata_definition)更改的情况，我们将发布一个修订版本，例如从 7.7.3 到 7.7.4。
有时我们会更改代码或元数据的内部结构，虽然不影响客户端的兼容性，但可能会影响该库**移植者**的兼容性。对于此类更改，我们会在 [libphonenumber-discuss](
https://groups.google.com/forum/#!forum/libphonenumber-discuss) 上发布公告。这些更改不会反映在版本号中，如果没有其他更改，我们将发布一个修订版本。
想要收到新版本发布的通知吗？在一年的大部分时间里，除假期和特殊情况外，我们每两周发布一次。我们会更新[发布标签](https://github.com/google/libphonenumber/releases)并记录详细的[发布说明](
https://github.com/google/libphonenumber/blob/master/release_notes.txt)。
我们还会在每次发布时向 [libphonenumber-discuss](
https://groups.google.com/forum/#!forum/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));
```
## 将电话号码映射到原始运营商
注意事项：我们不提供有关电话号码当前运营商的数据，仅提供分配了相应号段的原始运营商。请阅读关于[号码可携性](FAQ.md#what-is-mobile-number-portability)的内容。
```
PhoneNumber swissMobileNumber =
new PhoneNumber().setCountryCode(41).setNationalNumber(798765432L);
PhoneNumberToCarrierMapper carrierMapper = PhoneNumberToCarrierMapper.getInstance();
// Outputs "Swisscom"
System.out.println(carrierMapper.getNameForNumber(swissMobileNumber, Locale.ENGLISH));
```
关于如何使用该库的更多示例可以在[单元测试](https://github.com/google/libphonenumber/tree/master/java/libphonenumber/test/com/google/i18n/phonenumbers)中找到。
# 第三方移植
我们知道有几个第三方电话号码库移植版本。我们在此分享它们，以便对开发者有所帮助。
但是，我们强调这些移植版本是由 libphonenumber 项目之外的开发者提供的。我们不评估它们的质量，也不影响它们的维护过程。
* C#: https://github.com/twcclegg/libphonenumber-csharp
* Gleam: https://github.com/massivefermion/phony
* Go: https://github.com/nyaruka/phonenumbers
* Objective-c: https://github.com/iziz/libPhoneNumber-iOS
* Swift: https://github.com/marmelroy/PhoneNumberKit
* PHP: https://github.com/giggsey/libphonenumber-for-php
* PostgreSQL in-database types: https://github.com/blm768/pg-libphonenumber
* Python: https://github.com/daviddrysdale/python-phonenumbers
* Ruby: https://github.com/ianks/mini_phone
* Ruby: https://github.com/daddyz/phonelib
* Ruby: https://github.com/mobi/telephone_number
* Rust: https://github.com/vloldik/rlibphonenumber
* Rust: https://github.com/1aim/rust-phonenumber
* Erlang: https://github.com/marinakr/libphonenumber_erlang
* Clojure: https://github.com/randomseed-io/phone-number
* R: https://github.com/socialresearchcentre/dialr/
* Elixir: https://github.com/socialpaymentsbv/ex_phone_number
* Salesforce: https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3A00000G12oJUAR
* Dart: https://github.com/superakabo/dlibphonenumber
我们自有版本的替代方案：
* 针对 Android 优化：我们的 Java 版本从
`Class#getResourcesAsStream` 加载元数据，并要求 Android 应用遵循 Android 加载最佳实践，自行重新打包元数据并从
`AssetManager#open()` 加载
（[常见问题解答](https://github.com/google/libphonenumber/blob/master/FAQ.md#optimize-loads)）。
如果您不想这样做，可以查看位于
https://github.com/MichaelRocks/libphonenumber-android 的移植版本，它确实重新打包了元数据并使用了 `AssetManager#open()`，并且无需客户端进行那些特定的加载优化即可依赖。您还应该查看位于 https://github.com/lionscribe/libphonenumber-android 的移植版本，它也支持地理编码，并且只需更改一行代码。
* Javascript：如果您不想使用我们依赖 Closure 的版本，还有其他几个选项，包括
https://github.com/catamphetamine/libphonenumber-js - 一个精简的重写版本，大小约为 110 KB - 以及
https://github.com/seegno/google-libphonenumber - 一个与 browserify 兼容的封装，围绕可通过 npm 安装的原始未修改库，打包了 Google Closure 库，大小约为 420 KB。
基于 libphonenumber 元数据的工具：
* Scala: https://github.com/mr-tolmach/raf - 用于生成 E.164 格式有效电话号码的库
标签：Android开发, AsYouTypeFormatter, C++, CMS安全, Google, JavaScript, JS文件枚举, libphonenumber, Nuclei, SEO关键词：JavaScript手机号校验, SEO关键词：国际电话号码格式, SEO关键词：手机号验证API, 后端开发, 国际手机号, 字符串处理, 开源库, 搜索引擎爬虫, 数据可视化, 数据擦除, 数据验证, 文本提取, 电话号码格式化, 电话号码解析, 离线地理编码, 输入校验, 通信处理