awesome phonenumber

Pengurai nomor telepon yang luar biasa

Pustaka ini adalah versi libphonenumber Google yang telah dikompilasi sebelumnya, dengan antarmuka yang sedikit lebih sederhana. Ini memiliki jejak minimal - sejauh ini merupakan perpustakaan berbasis libphonenumber terkecil yang tersedia di npmjs, dan tidak memiliki ketergantungan.

Tidak seperti libphonenumber, ini menyertakan fungsi findNumbers( ) untuk menemukan nomor telepon dalam teks.

Pengetikan TypeScript disediakan dalam paket.

Menggunakan libphonenumber v8.13.47

Versi

• v3:

• API yang diubah (meskipun dengan ABI yang kompatibel)

• Menambahkan ekspor ESM

• v4:

• Argumen kedua untuk parsePhoneNumber adalah sebuah objek

• Nilai yang dikembalikan seperti toJSON( ) di v3

• Misalnya { regionCode: 'SE' } alih-alih string kode wilayah

• Tidak ada konstruktor

• Tidak ada fungsi pada objek yang dikembalikan

• Tidak ada kesalahan yang terjadi

• Mengubah API menjadi lebih bersih

• Tidak kompatibel ke belakang, meskipun seperti v3 kecuali:

• v5:

• Menghapus dukungan Node 12

• v6:

• Menghapus dukungan Node 16

• v7:

• Menambahkan fitur findNumbers( ) , untuk menemukan nomor telepon dalam teks

• Menambahkan dukungan untuk nomor pendek

Perbandingan dengan perpustakaan lain

Karena perpustakaan ini sudah dikompilasi sebelumnya, perpustakaan ini tidak bergantung pada kompiler penutupan, dan tidak perlu memuatnya saat awal. Ini membuat perpustakaan lebih cepat dan menghemat banyak ruang. Ini juga berarti perpustakaan ini mudah digunakan dalam proyek webpack apa pun (atau menggunakan cara lain apa pun untuk dijalankan di browser).

Di antara semua nomor telepon populer yang menggunakan libphonenumber Google (atau menirunya), hanya yang ini, google-libphonenumber dan libphonenumber-js yang memiliki README yang layak beserta contohnya. Hal ini mungkin sudah berubah sejak pertama kali melakukan benchmark tersebut .

Perpustakaan harus cepat dimuat ( require() ), cepat diurai untuk pertama kali dan berturut-turut. Seharusnya tidak membuat node_modules Anda membengkak, dan harus memiliki jejak memori yang kecil, jika memungkinkan.

Berikut ini adalah hasil pengujian program yang memuat perpustakaan, kemudian mem-parsing nomor telepon, dan sekali lagi. Ini dipanggil 100 kali untuk setiap perpustakaan dan nilai rata-rata ditampilkan di sini. Mengurai nomor telepon untuk pertama kalinya mungkin lebih lambat karena kompilasi/pengoptimalan ekspresi reguler pada awalnya dan yang lainnya. Menguraikan nomor telepon untuk kedua kalinya akan menunjukkan kecepatan kemungkinan semua penguraian di masa mendatang dalam proses tersebut.

Tindakan	nomor telepon yang luar biasa 2.56.0 (lib 8.12.29)	google-libphonenumber 3.2.22 (lib 8.12.27)	libphonenumber-js 1.9.23 (lib -)
Muat perpustakaan pertama kali	11,0 ms ✅	29,67 ms	32,87 ms
Parsing nomor telepon pertama	4,3 ms	4,01 mdtk	3,43 ms ✅
⇒ Muat + parsing nomor pertama	15,3 ms ✅	33,68 mdtk	36,3 ms
Parsing nomor telepon kedua	0,78 ms ✅	0,97 mdtk	0,92 ms
Peningkatan penggunaan memori	5,12 jt ✅	9,99 jt	5,86 jt
ukuran node_modules	296K ✅	600 K	7,6M
file node_modules	8	7 ✅	653

Penggunaan dasar

 import { parsePhoneNumber } from 'awesome-phonenumber'const pn = parsePhoneNumber( '0707123456', { regionCode: 'SE' } );// atau pada format e164:const pn = parsePhoneNumber( '[phone]' );// pn adalah sekarang sama dengan:const pn = {valid: benar,nomor: {input: '0707123456',e164: '[phone]',internasional: '[phone]',nasional: '070-712 34 56',rfc3966: 'telp:[phone]', signifikan: '707123456',},kemungkinan: 'mungkin',Kode Wilayah: 'SE',mungkin: benar,pendekKemungkinan: salah,pendekValid: salah,canBeInternationallyDialled: benar,ketik: 'seluler',Kode Negara: 46,typeIsMobile: benar, typeIsFixedLine: salah,};

Tipe yang dikembalikan adalah ParsedPhoneNumber yang merupakan ParsedPhoneNumberValid atau ParsedPhoneNumberInvalid . Properti valid mengidentifikasi apakah penguraian berhasil atau tidak, maka tipe mana yang dikembalikan.

Format parsing yang berhasil adalah:

 antarmuka ParsedPhoneNumberValid {valid: true;number: {input: string;internasional: string;nasional: string;e164: string;rfc3966: string;signifikan: string;};kemungkinan: PhoneNumberPossibility; // gabungan string, lihat di bawahregionCode: string;possible: boolean;shortPossible: boolean;shortValid: boolean;canBeInternationallyDialled: boolean;type: PhoneNumberTypes; // gabungan string, lihat di bawahkode negara: number;typeIsMobile: boolean;typeIsFixedLine: boolean;}

Jika nomor gagal diuraikan, atau terjadi kesalahan lain, tipe pengembaliannya adalah:

 antarmuka ParsedPhoneNumberInvalid {valid: false;possible: false;possibility: 'invalid';shortPossible: boolean;shortValid: boolean;error?: unknown;};

Perhatikan bahwa nomor telepon yang salah (tidak valid) masih bisa menjadi nomor pendek yang valid untuk wilayah tertentu.

API

 impor {parsePhoneNumber,findNumbers,getNumberFrom,getExample,getCountryCodeForRegionCode,getRegionCodeForCountryCode,getSupportedCallingCodes,getSupportedRegionCodes,getAsYouType,} dari 'nomor telepon yang luar biasa'

parseNomor Telepon

parsePhoneNumber( phoneNumber, { regionCode: string } ) mem-parsing nomor telepon seperti dijelaskan di atas.

Argumen pertama adalah nomor telepon yang akan diurai, baik dalam bentuk nasional atau internasional (e164, yaitu diawali dengan + ). Jika berbentuk nasional , argumen kedua harus berisi properti string regionCode , misalnya 'SE' untuk Swedia, 'CH' untuk Swiss, dll.

temukanNomor

Untuk menemukan (mengekstrak) nomor telepon dalam teks, gunakan findNumbers( ) :

 import { findNumbers } from 'awesome-phonenumber'const text = 'Nomor saya [phone], jika tidak, hubungi [phone].';const number = findNumbers( text );

Daftar nomor yang dikembalikan adalah tipe PhoneNumberMatch seperti:

 antarmuka PhoneNumberMatch{teks: string; // String mentah foundphoneNumber: object; // Sama seperti hasil parsePhoneNumber()start: number; // Mulai offset di textend: number; // Akhiri offset dalam teks}

Argumen opsi kedua untuk findNumbers( text, options ) dapat diberikan pada formulir:

 antarmuka FindNumbersOptions{defaultRegionCode?: string;leniency?: FindNumbersLeniency;maxTries?: number;}

di mana FindNumbersLeniency adalah enum dari 'valid' atau 'possible' . Standarnya adalah 'valid' artinya hanya nomor telepon valid yang ditemukan. Jika ini disetel ke 'possible' nomor telepon yang mungkin juga ditemukan (tetapi tidak valid).

defaultRegionCode dapat diatur (misalnya ke 'SE' untuk Swedia), dalam hal ini nomor telepon pada formulir nasional (yaitu tanpa awalan + ) akan ditemukan, asalkan berasal dari wilayah tersebut.

Untuk teks yang sangat besar, maxTries akan mengatur jumlah maksimum nomor telepon yang akan dicari (sebenarnya tidak perlu ditemukan).

dapatkanNomorDari

 impor { parsePhoneNumber, getNumberFrom } dari 'awesome-phonenumber'const pn = parsePhoneNumber( '0707654321', { regionCode: 'SE' } );if ( pn.valid ) {const fromJp = getNumberFrom( pn, 'JP' );/ / fromJp adalah nomor yang dapat dihubungi dari Jepang:fromJp.number === "010 46 70 765 43 21";}

Nilai kembalian dari getNumberFrom adalah PhoneNumberFrom yang merupakan PhoneNumberFromValid atau PhoneNumberFromInvalid .

PhoneNumberFromValid didefinisikan sebagai:

 antarmuka PhoneNumberFromValid{valid: true;number: string;}

PhoneNumberFromInvalid didefinisikan sebagai:

 antarmuka PhoneNumberFromInvalid{valid: false;error?: unknown;}

dapatkan Contoh

Terkadang Anda ingin menampilkan contoh nomor telepon yang diformat untuk negara tertentu (dan mungkin juga jenis nomor telepon tertentu). Fungsi getExample digunakan untuk ini.

 impor { getExample } dari 'nomor telepon mengagumkan'getExample( regionCode[, phoneNumberType] ); // Nomor telepon yang diurai

phoneNumberType adalah salah satu tipe yang ditentukan di atas.

Contoh

 import { getExample } from 'awesome-phonenumber'// Dapatkan contoh nomor telepon Swediaconst example = getExample( 'SE' ); // ParsedPhoneNumberValidconst exampleMobile = getExample( 'SE', 'mobile' ); // Sebuah ParsedPhoneNumberValidexample.number.e164;           // misalnya '[phone]'exampleMobile.number.e164;     // misalnya '[phone]'exampleMobile.number.national; // misalnya '070 123 45 67'

Kode negara

Terdapat fungsi konversi antara 2 karakter kode wilayah ISO 3166-1 (misalnya 'SE' untuk Swedia) dan kode panggilan negara terkait.

 impor {getCountryCodeForRegionCode,getRegionCodeForCountryCode,getSupportedCallingCodes,getSupportedRegionCodes,} dari 'awesome-phonenumber'getCountryCodeForRegionCode( regionCode );  // -> countryCodegetRegionCodeForCountryCode( kode negara ); // -> Kode wilayah

Contoh

 getCountryCodeForRegionCode( 'SE' ); // -> 46getRegionCodeForCountryCode( 46 );   // -> 'SE'

Kode panggilan yang didukung

 getSupportedCallingCodes( ); // -> [ kode panggilan... ]

Kode wilayah yang didukung

 getSupportedRegionCodes(); // -> [ kode wilayah... ]

Jenis API

API terdiri dari kelas PhoneNumber yang terkadang menggunakan enums . Ini adalah:

Jenis nomor telepon

 ketik PhoneNumberTypes =| 'jalur tetap'| 'jalur tetap atau seluler'| 'ponsel'| 'pager'| 'nomor pribadi'| 'tarif premium'| 'biaya bersama'| 'bebas pulsa'| 'uan'| 'voip'| 'tidak dikenal'

Kemungkinan nomor telepon

 ketik PhoneNumberPossibility =| 'mungkin'| 'kode negara tidak valid'| 'terlalu lama'| 'terlalu pendek'| 'tidak dikenal'

Format nomor telepon

 'internasional''nasional''e164''rfc3966''signifikan'

Pemformatan saat Anda mengetik

Anda dapat membuat kelas AsYouType dengan getAsYouType() untuk memformat nomor telepon saat sedang diketik.

 impor { getAsYouType } dari 'nomor telepon-awesome'const ayt = getAsYouType( 'SE' );

Contoh kelas yang dikembalikan memiliki metode berikut

 // Tambahkan karakter di akhir numberayt.addChar( nextChar: string );// Dapatkan format numberayt.number( );// Hapus karakter terakhirayt.removeChar( );// Ganti bilangan bulat dengan a nomor baru (atau nomor kosong jika tidak ditentukan)ayt.reset( number?: string );// Dapatkan objek ParsedPhoneNumber yang mewakili numberayt.getPhoneNumber( );

Semua fungsi di atas kecuali getPhoneNumber( ) mengembalikan nomor yang diformat saat ini sebagai string.

Contoh

 impor { getAsYouType } dari 'nomor telepon-awesome'const ayt = getAsYouType( 'SE' );ayt.addChar( '0' ); // -> '0'ayt.addChar( '7' ); // -> '07'ayt.addChar( '0' ); // -> '070'ayt.addChar( '7' ); // -> '070 7'ayt.addChar( '1' ); // -> '070 71'ayt.addChar( '2' ); // -> '070 712'ayt.addChar( '3' ); // -> '070 712 3'ayt.addChar( '4' ); // -> '070 712 34'ayt.addChar( '5' ); // -> '070 712 34 5'ayt.addChar( '6' ); // -> '070 712 34 56'ayt.removeChar( );  // -> '070 712 34 5'ayt.addChar( '7' ); // -> '070 712 34 57'