entrée de téléphone international

Entrée téléphonique internationale

NEWS : nous avons désormais notre propre composant Vue !

NEWS : nous avons désormais notre propre composant React ! Jouez avec sur Storybook.

?️ NEWS : nous proposons désormais des traductions dans plus de 30 langues ! Voyez-les en action.

International Telephone Input est un plugin JavaScript permettant de saisir et de valider des numéros de téléphone internationaux. Il prend un champ de saisie standard, ajoute une liste déroulante de pays consultable, détecte automatiquement le pays de l'utilisateur, affiche un numéro d'espace réservé pertinent, formate le numéro au fur et à mesure que vous tapez et fournit des méthodes de validation complètes. Les composants React et Vue sont également inclus.

Si vous trouvez le plugin utile, pensez à soutenir le projet.

Parrainé par

Utilisez l'API de Twilio pour créer une vérification téléphonique, des SMS 2FA, des rappels de rendez-vous, des notifications marketing et bien plus encore. Nous avons hâte de voir ce que vous construisez.

Table des matières

• Composants React et Vue
• Démo et exemples
• Mobile
• Caractéristiques
• Compatibilité du navigateur
• Commencer
• Utilisation recommandée
• Options d'initialisation
• Méthodes d'instance
• Méthodes statiques
• Événements
• Thème / Mode sombre
• Traductions
• Script utilitaire
• Chargement du script des utilitaires
• Dépannage
• Contribuer
• Attributions

Composants React et Vue

Nous fournissons désormais les composants React et Vue ainsi que le plugin JavaScript standard. Ce fichier Lisez-moi concerne le plugin JavaScript. Consultez le fichier Lisez-moi du composant React ou le fichier Lisez-moi du composant Vue.

Démo et exemples

Vous pouvez visionner une démo en direct et voir quelques exemples d’utilisation des différentes options. Vous pouvez également l'essayer par vous-même en téléchargeant le projet et en ouvrant demo.html dans un navigateur.

Mobile

Par défaut, sur les appareils mobiles, nous affichons une fenêtre contextuelle en plein écran au lieu de la liste déroulante en ligne, afin de mieux utiliser l'espace limité de l'écran. Ceci est similaire au fonctionnement d’un élément natif. Vous pouvez contrôler ce comportement avec l'option useFullscreenPopup . La fenêtre contextuelle peut être fermée soit en sélectionnant un pays dans la liste, soit en appuyant sur la zone grise sur les côtés. Voir exemple (en utilisant le composant React).

Caractéristiques

• Sélectionnez automatiquement le pays actuel de l'utilisateur à l'aide d'une recherche IP
• Définir automatiquement l'espace réservé de saisie sur un exemple de numéro pour le pays sélectionné
• Naviguez dans la liste déroulante des pays en tapant le nom d'un pays ou en utilisant les touches haut/bas
• Formater automatiquement le numéro au fur et à mesure que l'utilisateur tape
• En option, autorisez uniquement les caractères numériques et limitez le nombre à la longueur maximale valide.
• L'utilisateur saisit son numéro national et le plugin vous donne le numéro international standardisé complet
• Validation des numéros, y compris les types d'erreurs spécifiques
• Images de drapeaux haute résolution
• Accessibilité assurée via les balises ARIA
• Définitions de types dactylographiées incluses
• Personnalisez facilement les styles en remplaçant les variables CSS
• Composants React et Vue également inclus
• Traductions des noms de pays (etc.) fournies dans de nombreuses langues différentes
• De nombreuses options d'initialisation pour la personnalisation, ainsi que des méthodes/événements d'instance pour l'interaction

Compatibilité du navigateur

Chrome	Firefox	Safari	Bord
✓	✓	v14+	✓

Remarque : Nous avons désormais abandonné la prise en charge de toutes les versions d'Internet Explorer, car elles ne sont plus prises en charge par aucune version de Windows.

Premiers pas (utilisation d'un CDN)

1. Ajouter le CSS

">

 < link rel =" stylesheet " href =" https://cdn.jsdelivr.net/npm/[email protected]/build/css/intlTelInput.css " >

2. Ajoutez le script du plugin et initialisez-le sur votre élément d'entrée

">

 < script src =" https://cdn.jsdelivr.net/npm/[email protected]/build/js/intlTelInput.min.js " >  script >
< script >
  const input = document . querySelector ( "#phone" ) ;
  window . intlTelInput ( input , {
    loadUtilsOnInit : "https://cdn.jsdelivr.net/npm/[email protected]/build/js/utils.js" ,
  } ) ;
 script > 

Mise en route (utilisation d'un bundler, par exemple Webpack)

1. Installer avec npm : npm install intl-tel-input --save ou fil : yarn add intl-tel-input

2. Importez le CSS : import 'intl-tel-input/build/css/intlTelInput.css';

3. Définissez le chemin vers flags.webp et globe.webp dans votre CSS, en remplaçant les variables CSS

. iti {
  --iti-path-flags-1x : url ( 'path/to/flags.webp' );
  --iti-path-flags-2x : url ( 'path/to/[email protected]' );
  --iti-path-globe-1x : url ( 'path/to/globe.webp' );
  --iti-path-globe-2x : url ( 'path/to/[email protected]' );
}

4. Importez le JS et initialisez le plugin sur votre élément d'entrée

import("intl-tel-input/utils") });">

 import intlTelInput from 'intl-tel-input' ;

const input = document . querySelector ( "#phone" ) ;
intlTelInput ( input , {
    loadUtilsOnInit : ( ) => import ( "intl-tel-input/utils" )
} ) ;

La plupart des bundles (tels que Webpack, Vite ou Parcel) verront cela et placeront le script des utilitaires dans un bundle séparé et le chargeront de manière asynchrone, uniquement en cas de besoin. Si cela ne fonctionne pas avec votre bundler ou si vous souhaitez charger le module utils à partir d'un autre emplacement (comme un CDN), vous pouvez définir l'option loadUtilsOnInit sur l'URL à partir de laquelle charger sous forme de chaîne. Par exemple:

 import intlTelInput from 'intl-tel-input' ;

const input = document . querySelector ( "#phone" ) ;
intlTelInput ( input , {
    loadUtilsOnInit : `https://cdn.jsdelivr.net/npm/intl-tel-input@ ${ intlTelInput . version } /build/js/utils.js` ;
} ) ; 

Mise en route (sans utiliser de bundler)

1. Téléchargez la dernière version, ou mieux encore, installez-la avec npm

2. Ajouter la feuille de style

">

 < link rel =" stylesheet " href =" path/to/intlTelInput.css " >

3. Définissez le chemin vers flags.webp et globe.webp dans votre CSS, en remplaçant les variables CSS

. iti {
  --iti-path-flags-1x : url ( 'path/to/flags.webp' );
  --iti-path-flags-2x : url ( 'path/to/[email protected]' );
  --iti-path-globe-1x : url ( 'path/to/globe.webp' );
  --iti-path-globe-2x : url ( 'path/to/[email protected]' );
}

4. Ajoutez le script du plugin et initialisez-le sur votre élément d'entrée

">

 < script src =" path/to/intlTelInput.js " >  script >
< script >
  const input = document . querySelector ( "#phone" ) ;
  window . intlTelInput ( input , {
    loadUtilsOnInit : "path/to/utils.js"
  } ) ;
 script > 

Utilisation recommandée

Nous vous recommandons fortement de charger le fichier utils.js inclus, qui permet le formatage et la validation, etc. Ensuite, le plugin est conçu pour toujours traiter les nombres au format international complet (par exemple "[phone]") et les convertir en conséquence - même lorsque nationalMode ou separateDialCode est activé. Nous vous recommandons d'obtenir, de stocker et de définir des numéros exclusivement dans ce format pour plus de simplicité. Vous n'aurez alors pas à gérer l'indicatif du pays séparément, car les numéros internationaux complets incluent les informations sur l'indicatif du pays.

Vous pouvez toujours obtenir le numéro international complet (y compris le code du pays) en utilisant getNumber , il vous suffit alors de stocker cette chaîne dans votre base de données (vous n'avez pas besoin de stocker le pays séparément), puis la prochaine fois que vous initialiserez le plugin. avec ce numéro en entrée, il définira automatiquement le pays et le formatera en fonction des options que vous spécifiez (par exemple, lors de l'utilisation nationalMode il affichera automatiquement le numéro au format national, en supprimant l'indicatif international).

Si vous connaissez le pays de l'utilisateur, vous pouvez le définir avec initialCountry (par exemple "us" pour les États-Unis), et si vous ne le savez pas, nous vous recommandons de définir initialCountry sur "auto" (avec l'option geoIpLookup ) pour déterminer le pays de l'utilisateur. pays en fonction de leur adresse IP - voir exemple.

Si vous connaissez la langue de l'utilisateur, vous pouvez utiliser les traductions incluses pour localiser les noms de pays (etc) - voir exemple.

Options d'initialisation

Lorsque vous initialisez le plugin, le premier argument est l'élément d'entrée et le second est un objet contenant toutes les options d'initialisation souhaitées, qui sont détaillées ci-dessous. Remarque : toutes les options qui acceptent des codes de pays doivent être des codes ISO 3166-1 alpha-2.

autoriserDropdown
Type : Boolean par défaut : true
S'il faut ou non autoriser la liste déroulante. S'il est désactivé, il n'y a pas de flèche déroulante et le pays sélectionné n'est pas cliquable. De plus, si showFlags est activé, nous affichons le drapeau sélectionné à droite car il ne s'agit que d'un marqueur d'état. Notez que si separateDialCode est activé, allowDropdown est forcé à true car la liste déroulante est requise lorsque l'utilisateur tape "+" dans ce cas. Jouez avec cette option sur Storybook (en utilisant le composant React).

espace réservé automatique
Type : String Valeur par défaut : "polite"
Définissez l'espace réservé de l'entrée sur un exemple de numéro pour le pays sélectionné et mettez-le à jour si le pays change. Vous pouvez spécifier le type de numéro à l’aide de l’option placeholderNumberType . Par défaut, il est défini sur "polite" , ce qui signifie qu'il ne définira l'espace réservé que si l'entrée n'en a pas déjà un. Vous pouvez également le définir sur "aggressive" , qui remplacera tout espace réservé existant, ou sur "off" . Nécessite le chargement du script utils.

conteneurClass
Type : String Valeur par défaut : ""
Classes supplémentaires à ajouter au wrapper (injecté)

.

paysCommander
Type : Array par défaut : null
Spécifiez l'ordre de la liste des pays avec un tableau de codes de pays iso2. Tous les pays omis apparaîtront après ceux spécifiés, par exemple en définissant countryOrder sur ["jp", "kr"] entraînera la liste : Japon, Corée du Sud, Afghanistan, Albanie, Algérie, etc...

paysRecherche
Type : Boolean par défaut : true
Ajoutez une entrée de recherche en haut de la liste déroulante afin que les utilisateurs puissent filtrer les pays affichés.

personnaliséPlaceholder
Type : Function Par défaut : null
Modifiez l'espace réservé généré par autoPlaceholder. Doit renvoyer une chaîne.

 intlTelInput ( input , {
  customPlaceholder : function ( selectedCountryPlaceholder , selectedCountryData ) {
    return "e.g. " + selectedCountryPlaceholder ;
  } ,
} ) ;

dropdownConteneur
Type : Node par défaut : null
Attend un nœud, par exemple document.body . Au lieu de placer le balisage déroulant du pays à côté de l'entrée, ajoutez-le au nœud spécifié, et il sera ensuite positionné à côté de l'entrée à l'aide de JavaScript (en utilisant position: fixed ). Ceci est utile lorsque l'entrée se trouve à l'intérieur d'un conteneur avec overflow: hidden . Notez que le positionnement est interrompu par le défilement, donc la liste déroulante se fermera automatiquement lors de l'événement de défilement window .

exclurePays
Type : Array Par défaut : []
Dans la liste déroulante, affichez tous les pays sauf ceux que vous spécifiez ici. Jouez avec cette option sur Storybook (en utilisant le composant React).

fixDropdownWidth
Type : Boolean par défaut : true
Fixez la largeur de la liste déroulante à la largeur de saisie (plutôt que d'être aussi large que le nom de pays le plus long). Jouez avec cette option sur Storybook (en utilisant le composant React).

formatAsYouType
Type : Boolean par défaut : true
Formatez automatiquement le numéro au fur et à mesure que l'utilisateur le tape. Cette fonctionnalité sera désactivée si l'utilisateur saisit ses propres caractères de formatage. Nécessite le chargement du script utils.

formatSurAffichage
Type : Boolean par défaut : true
Formatez la valeur d'entrée (selon l'option nationalMode ) lors de l'initialisation, et sur setNumber . Nécessite le chargement du script utils.

rechercheGeoIp
Type : Function Par défaut : null
Lorsque vous définissez initialCountry sur "auto" , vous devez utiliser cette option pour spécifier une fonction personnalisée qui appelle un service de recherche IP pour obtenir l'emplacement de l'utilisateur, puis appelle le rappel success avec le code du pays concerné. Notez également que lors de l'instanciation du plugin, un objet Promise est renvoyé sous la propriété d'instance promise , vous pouvez donc faire quelque chose comme iti.promise.then(...) pour savoir quand des demandes d'initialisation comme celle-ci sont terminées.

Voici un exemple utilisant le service ipapi :

 intlTelInput ( input , {
  initialCountry : "auto" ,
  geoIpLookup : function ( success , failure ) {
    fetch ( "https://ipapi.co/json" )
      . then ( function ( res ) { return res . json ( ) ; } )
      . then ( function ( data ) { success ( data . country_code ) ; } )
      . catch ( function ( ) { failure ( ) ; } ) ;
  }
} ) ;

Notez que le rappel failure doit être appelé en cas d'erreur, d'où l'utilisation de catch() dans cet exemple. Astuce : stockez le résultat dans un cookie pour éviter les recherches répétées !

entrée masquée
Type : Function Par défaut : null
Permet la création de champs de saisie masqués dans un formulaire pour stocker le numéro de téléphone international complet et l'indicatif du pays sélectionné. Il accepte une fonction qui reçoit en argument le nom de l'entrée téléphonique principale. Cette fonction doit renvoyer un objet avec les propriétés phone et (éventuellement) country pour spécifier respectivement les noms des entrées masquées pour le numéro de téléphone et l'indicatif du pays. Ceci est utile pour les soumissions de formulaires non-Ajax afin de garantir que le numéro international complet et le code du pays sont capturés, en particulier lorsque nationalMode est activé.

* Remarque : Cette fonctionnalité nécessite que l'entrée soit à l'intérieur d'un élément

, car elle écoute l'événement submit sur l'élément de formulaire le plus proche. Notez également que puisque cela utilise getNumber en interne, d'une part, il nécessite que le script utils soit chargé, et d'autre part, il attend un numéro valide et ne fonctionnera donc correctement que si vous avez utilisé isValidNumber pour valider le numéro avant d'autoriser la soumission du formulaire.

 intlTelInput ( input , {
  hiddenInput : function ( telInputName ) {
    return {
      phone : "phone_full" ,
      country : "country_code"
    } ;
  }
} ) ;

Cela générera les éléments (cachés) suivants, qui seront automatiquement renseignés lors de la soumission :

">

 < input type =" hidden " name =" phone_full " >
< input type =" hidden " name =" country_code " >