awesome phonenumber

Analisador de número de telefone incrível

Esta biblioteca é uma versão pré-compilada do libphonenumber do Google, com uma interface um pouco mais simples. Ela ocupa um espaço mínimo - é de longe a menor biblioteca baseada em libphonenumber disponível no npmjs e não possui dependências.

Ao contrário de libphonenumber, inclui uma função findNumbers( ) para localizar números de telefone em texto.

As tipificações TypeScript são fornecidas no pacote.

Usa libphonenumber v8.13.47

Versões

• v3:

• API alterada (embora com ABI compatível com versões anteriores)

• Adicionada exportação ESM

• v4:

• O segundo argumento para parsePhoneNumber é um objeto

• O valor de retorno é como toJSON( ) na v3

• Por exemplo, { regionCode: 'SE' } em vez de uma string de código de região

• Nenhum construtor

• Nenhuma função no objeto retornado

• Nenhum erro sendo lançado

• API alterada para ser muito mais limpa

• Não é compatível com versões anteriores, embora seja semelhante à v3, exceto:

• v5:

• Suporte ao Nó 12 descartado

• v6:

• Suporte ao Node 16 descartado

• v7:

• Adicionado recurso findNumbers( ) , para encontrar números de telefone em texto

• Adicionado suporte para números curtos

Comparação com outras bibliotecas

Como esta biblioteca é pré-compilada, ela não depende do compilador de encerramento e não precisa carregá-la na inicialização. Isso torna a biblioteca mais rápida e economiza muito espaço. Isso também significa que esta biblioteca é trivial para usar em qualquer projeto webpack (ou usar qualquer outro meio para executar no navegador).

Entre todos os números de telefone populares que usam libphonenumber do Google (ou que o imitam), apenas este, google-libphonenumber e libphonenumber-js têm READMEs decentes com exemplos. Isso pode ter mudado desde a primeira vez que fizemos esses benchmarks .

Uma biblioteca deve ser rápida para carregar ( require() ), rápida para analisar na primeira vez e em todas as vezes consecutivas. Ele não deve sobrecarregar seu node_modules e deve ocupar pouco espaço de memória, se possível.

A seguir está o resultado de um programa de teste que carrega a biblioteca, analisa um número de telefone e novamente. É chamado 100 vezes para cada biblioteca e os valores médios são mostrados aqui. A análise de um número de telefone na primeira vez pode ser mais lenta devido à compilação/otimização inicial de expressões regulares e outros enfeites. A análise de um número de telefone uma segunda vez mostrará a velocidade de provavelmente todas as análises futuras nesse processo.

Ação	número de telefone incrível 2.56.0 (lib 8.12.29)	número de telefone google-lib 3.2.22 (lib 8.12.27)	libphonenumber-js 1.9.23 (lib-)
Carregar biblioteca pela primeira vez	11,0m ✅	29,67ms	32,87ms
Analisar o primeiro número de telefone	4,3ms	4,01ms	3,43ms ✅
⇒ Carregar + analisar o primeiro número	15,3ms ✅	33,68ms	36,3ms
Analisar segundo número de telefone	0,78ms ✅	0,97ms	0,92ms
Maior uso de memória	5,12 milhões ✅	9,99 milhões	5,86 milhões
tamanho de node_modules	296 mil ✅	600 mil	7,6 milhões
arquivos node_modules	8	7 ✅	653

Uso básico

 import { parsePhoneNumber } from 'awesome-phonenumber'const pn = parsePhoneNumber( '0707123456', { regionCode: 'SE' } );// ou no formato e164:const pn = parsePhoneNumber( '[phone]' );// pn é agora é o mesmo que: const pn = {válido: verdadeiro, número: {entrada: '0707123456',e164: '[phone]',internacional: '[phone]',nacional: '070-712 34 56',rfc3966: 'tel:[phone] ',significativo: '707123456',},possibilidade: 'é-possível',regionCode: 'SE',possível: true,shortPossible: false,shortValid: false,canBeInternationallyDialled: true,type: 'mobile',countryCode: 46,typeIsMobile: true, typeIsFixedLine: falso,};

O tipo de retorno é ParsedPhoneNumber que é ParsedPhoneNumberValid ou ParsedPhoneNumberInvalid . A propriedade valid identifica se a análise foi bem-sucedida ou não, portanto, qual tipo é retornado.

O formato de uma análise bem-sucedida é:

 interface ParsedPhoneNumberValid {válido: verdadeiro;número: {entrada: string;internacional: string;nacional: string;e164: string;rfc3966: string;significativo: string;};possibilidade: PhoneNumberPossibility; // uma união de strings, veja abaixoregionCode: string;possible: boolean;shortPossible: boolean;shortValid: boolean;canBeInternationallyDialled: boolean;type: PhoneNumberTypes; // uma união de strings, veja abaixocountryCode: number;typeIsMobile: boolean;typeIsFixedLine: boolean;}

Se o número não foi analisado ou houve outro erro, o tipo de retorno será:

 interface ParsedPhoneNumberInvalid {válido: falso;possível: falso;possibilidade: 'inválido';shortPossible: booleano;shortValid: booleano;erro?: desconhecido;};

Observe que um número de telefone incorreto (inválido) ainda pode ser um número curto válido para uma determinada região.

API

 importar {parsePhoneNumber,findNumbers,getNumberFrom,getExample,getCountryCodeForRegionCode,getRegionCodeForCountryCode,getSupportedCallingCodes,getSupportedRegionCodes,getAsYouType,} de 'awesome-phonenumber'

analisarNúmero de telefone

parsePhoneNumber( phoneNumber, { regionCode: string } ) analisa um número de telefone conforme descrito acima.

O primeiro argumento é o número de telefone a ser analisado, no formato nacional ou internacional (e164, ou seja, prefixado com + ). Se for na forma nacional , o segundo argumento deverá conter uma propriedade de string regionCode , por exemplo, 'SE' para a Suécia, 'CH' para a Suíça, etc.

encontrar números

Para encontrar (extrair) números de telefone no texto, use findNumbers( ) :

 import { findNumbers } from 'awesome-phonenumber'const text = 'Meu número é [phone], caso contrário ligue para [phone].';const numbers = findNumbers( text );

A lista de números retornada é do tipo PhoneNumberMatch como:

 interface PhoneNumberMatch{texto: string; // A string bruta foundphoneNumber: object; // Igual ao resultado de parsePhoneNumber()start: number; //Iniciar deslocamento no textend: number; //Deslocamento final no texto}

Um segundo argumento de opções para findNumbers( text, options ) pode ser fornecido no formulário:

 interface FindNumbersOptions{defaultRegionCode?: string;leniency?: FindNumbersLeniency;maxTries?: número;}

onde FindNumbersLeniency é uma enumeração de 'valid' ou 'possible' . O padrão é 'valid' o que significa que apenas números de telefone válidos são encontrados. Se estiver definido como 'possible' também serão encontrados números de telefone possíveis (mas inválidos).

defaultRegionCode pode ser definido (por exemplo, para 'SE' para a Suécia), caso em que serão encontrados números de telefone no formato nacional (ou seja, sem prefixo + ), desde que sejam daquela região.

Para textos realmente grandes, maxTries definirá o número máximo de números de telefone para tentar encontrar (não é necessário realmente encontrar).

obterNumberFrom

 import {parsePhoneNumber, getNumberFrom } from 'awesome-phonenumber'const pn = parsePhoneNumber( '0707654321', { regionCode: 'SE' } );if ( pn.valid ) {const fromJp = getNumberFrom( pn, 'JP' );/ /fromJp é o número para ligar do Japão:fromJp.number === "010 46 70 765 43 21";}

O valor de retorno de getNumberFrom é um PhoneNumberFrom que é um PhoneNumberFromValid ou um PhoneNumberFromInvalid .

O PhoneNumberFromValid é definido como:

 interface PhoneNumberFromValid{válido: verdadeiro;número: string;}

O PhoneNumberFromInvalid é definido como:

 interface PhoneNumberFromInvalid{válido: falso;erro?: desconhecido;}

obterExemplo

Às vezes, você deseja exibir um exemplo de número de telefone formatado para um determinado país (e talvez também um determinado tipo de número de telefone). A função getExample é usada para isso.

 importar { getExample } de 'awesome-phonenumber'getExample(regionCode[, phoneNumberType]); //Número de telefone analisado

O phoneNumberType é qualquer um dos tipos definidos acima.

Exemplo

 import { getExample } from 'awesome-phonenumber'// Obtenha um exemplo de número de telefone suecoconst example = getExample( 'SE' ); // Um ​​ParsedPhoneNumberValidconst exemploMobile = getExample( 'SE', 'mobile' ); // Um ​​ParsedPhoneNumberValidexample.number.e164;           // por exemplo, '[phone]'exampleMobile.number.e164;     // por exemplo, '[phone]'exampleMobile.number.national; // por exemplo, '070 123 45 67'

Códigos de país

Existem funções de conversão entre os códigos de região ISO 3166-1 de 2 caracteres (por exemplo, 'SE' para a Suécia) e os códigos de chamada do país correspondentes.

 importar {getCountryCodeForRegionCode,getRegionCodeForCountryCode,getSupportedCallingCodes,getSupportedRegionCodes,} de 'awesome-phonenumber'getCountryCodeForRegionCode(regionCode);  // -> countryCodegetRegionCodeForCountryCode( countryCode ); // -> código da região

Exemplo

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

Códigos de chamada suportados

 getSupportedCallingCodes(); // -> [chamando códigos...]

Códigos de região suportados

 getSupportedRegionCodes(); // -> [códigos de região...]

Tipos de API

A API consiste na classe PhoneNumber que às vezes usa enums . Estes são:

Tipos de número de telefone

 digite PhoneNumberTypes =| 'linha fixa'| 'linha fixa ou móvel' | 'móvel'| 'pager'| 'número pessoal' | 'taxa premium' | 'custo compartilhado' | 'ligação gratuita' | 'uan'| 'voip'| 'desconhecido'

Possibilidades de número de telefone

 digite PhoneNumberPossibilidade =| 'é possível'| 'código de país inválido' | 'muito longo' | 'muito curto' | 'desconhecido'

Formatos de número de telefone

 'internacional''nacional''e164''rfc3966''significativo'

Formatação conforme você digita

Você pode criar uma classe AsYouType com getAsYouType() para formatar um número de telefone enquanto ele é digitado.

 importar {getAsYouType} de 'awesome-phonenumber'const ayt = getAsYouType('SE');

A instância da classe retornada possui os seguintes métodos

 // Adiciona um caractere ao final do numberayt.addChar( nextChar: string );// Obtém o numberayt.number() formatado atual;// Remove o último caracterayt.removeChar( );// Substitui o número inteiro por um novo número (ou um número vazio se indefinido)ayt.reset( number?: string );// Obtém um objeto ParsedPhoneNumber representando o número atualayt.getPhoneNumber( );

Todas as funções acima, exceto getPhoneNumber( ) retornam o número formatado atual como uma string.

Exemplo

 importar { getAsYouType } de 'awesome-phonenumber'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'