阿西河

所有教程

公众号
🌙
阿西河前端的公众号

我的收藏

    最近访问  (文章)

      教程列表

      抓包专区
      测试专区

      插件 jQuery.International Telephone Input 中文 API 文档

      插件 jQuery.International Telephone Input 中文 API 文档

      https://github.com/jackocnr/intl-tel-input

      重要提示:自 v14 以来,我们已经删除了 jQuery 依赖项。请参阅下文,了解如何使用纯 JavaScript 初始化和使用该插件。如果你想坚持使用 jQuery 版本,现在有一个单独的 jQuery 包装版本。

      国际电话输入 建立状态

      用于输入和验证国际电话号码的 JavaScript 插件。它为任何输入添加标记下拉列表,检测用户的国家 / 地区,显示相关占位符并提供格式 / 验证方法。

      特征

      • 使用 IP 查找自动选择用户的当前国家 / 地区
      • 自动将输入占位符设置为所选国家 / 地区的示例编号
      • 通过键入国家 / 地区名称或使用向上 / 向下键来浏览国家 / 地区下拉列表
      • 处理电话号码扩展名
      • 用户键入他们的国家号码,插件为您提供完整的标准化国际号码
      • 完整验证,包括特定的错误类型
      • 视网膜标志图标
      • 许多用于定制的初始化选项,以及用于交互的公共方法

      入门

      下载最新版本,或者更好,然后使用 npm 安装它

      包括样式表

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

      覆盖 CSS 中 flags.png 的路径

      .iti-flag {background-image: url("path/to/flags.png");}
      
      @media (-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi) {
        .iti-flag {background-image: url("path/to/flags@2x.png");}
      }
      

      添加插件脚本并在输入元素上初始化它

      <input type="tel" id="phone">
      
      <script src="path/to/intlTelInput.js"></script>
      <script>
        var input = document.querySelector("#phone");
        window.intlTelInput(input);
      </script>
      
      

      建议:使用 utilsScript 启用格式化 / 验证的选项初始化插件,并允许您使用提取完整的国际号码 getNumber。

      推荐用法

      我们强烈建议您使用该 utilsScript 选项加载包含的 utils.js 。然后,插件构建为始终处理完整国际格式的数字(例如“+17024181234”)并相应地转换它们 - 即使启用 nationalMode 或 separateDialCode 启用。为了简单起见,我建议您以此格式获取,存储和设置号码 - 然后您不必单独处理国家 / 地区代码,因为完整的国际号码包括国家 / 地区代码信息。

      您始终可以使用完整的国际号码(包括国家 / 地区代码)getNumber,然后您只需要将一个字符串存储在数据库中(您不必单独存储国家 / 地区),然后在下次初始化插件时使用该号码将自动设置国家 / 地区并根据您指定的选项对其进行格式化(例如,如果您启用 nationalMode 它将自动删除国际拨号代码)。

      选项

      注意:任何采用国家 / 地区代码的选项都应为 ISO 3166-1 alpha-2 代码

      allowDropdown

      类型:Boolean 默认值:true 是否允许下拉列表。如果禁用,则没有下拉箭头,并且所选标志不可单击。此外,我们在右侧显示所选标志,因为它只是状态的标记。

      自动套用格式 [ REMOVED]

      在用户输入时自动格式化数字。不幸的是,由于此处列出的原因,必须将其删除:#346 禁用并删除自动套用格式功能。

      autoHideDialCode

      类型:Boolean 默认:true 如果输入中只有拨号代码:在模糊或提交时将其删除。这是为了防止拨打代码与表单一起提交。需要 nationalMode 设置为 false。

      autoPlaceholder

      类型:String 默认:“polite” 将输入的占位符设置为所选国家 / 地区的示例编号,并在国家 / 地区更改时更新。您可以使用该 placeholderNumberType 选项指定数字类型。默认情况下,它设置为"polite",这意味着如果输入尚未设置占位符,它将仅设置占位符。您也可以将其设置为"aggressive",将替换任何现有的占位符,或"off"。需要 utilsScript 选项。

      customContainer

      类型:String 默认值:"" 要添加到父 div 的其他类。

      customPlaceholder

      类型:Function 默认值:null 更改 autoPlaceholder 生成的占位符。必须返回一个字符串。

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

      dropdownContainer

      类型:Node 默认值:null 预期节点,例如 document.body。不要将国家 / 地区下拉列表放在输入旁边,而是将其附加到指定节点,然后使用 JavaScript 将其放置在输入旁边。当输入在容器内时,这很有用 overflow: hidden。请注意,可以通过滚动来打破绝对定位,因此它会自动关闭 window 滚动事件。

      excludeCountries

      类型:Array 默认值:undefined 在下拉列表中,显示除此处指定的国家 / 地区以外的所有国家 / 地区。

      formatOnDisplay

      类型:Boolean 默认值:在初始化期间 true 格式化输入值(根据 nationalMode 选项),然后打开 setNumber。需要 utilsScript 选项。

      geoIpLookup

      类型:Function 默认值:null 当设置 initialCountry 到"auto",您必须使用此选项来指定查找用户的位置,然后调用与有关国家代码的成功回调的自定义功能。另请注意,在实例化插件时,如果定义了 Promise 对象,则会在 promiseinstance 属性下返回其中一个,因此您可以执行类似的操作,iti.promise.then(callback) 以了解此类初始化请求何时完成。

      以下是使用 ipinfo.io 服务的示例:

      intlTelInput(input, {
        initialCountry: "auto",
        geoIpLookup: function(success, failure) {
          $.get("https://ipinfo.io", function() {}, "jsonp").always(function(resp) {
            var countryCode = (resp && resp.country) ? resp.country : "";
            success(countryCode);
          });
        },
      });
      

      请注意,在发生错误时仍必须调用回调,因此 always 在此示例中使用。 提示:将结果存储在 cookie 中以避免重复查找!

      hiddenInput

      类型:String 默认:"" 添加具有给定名称的隐藏输入(或者如果您的输入名称包含方括号,则它将为隐藏的输入提供相同的名称,用给定的名称替换括号的内容)。在提交时,使用完整的国际号码(使用 getNumber)填充它。对于使用非 ajax 表单的人来说,这是一种快速获取完整国际号码的方法,即使 nationalMode 已启用。注意:要求输入位于表单元素内,因为此功能通过在最近的表单元素上侦听 submit 事件来工作。另请注意,由于它在 getNumber 内部使用,因此需要有效数字,因此只应在验证后使用。

      initialCountry

      类型:String 默认:"" 通过指定其国家 / 地区代码来设置初始国家 / 地区选择。您也可以将其设置为"auto",它将根据用户的 IP 地址查找用户的国家 / 地区(需要 geoIpLookup 选项 - 请参阅示例)。请注意,“auto"如果输入已包含数字,则该选项不会更新国家 / 地区选择。

      如果您 initialCountry 留空,则默认为列表中的第一个国家 / 地区。

      localizedCountries

      类型:Object 默认:{} 允许通过给定的 iso 代码翻译国家 / 地区,例如:

      { 'de': 'Deutschland' }
      
      

      nationalMode

      类型:Boolean 默认:true 允许用户输入国家号码(而不必考虑国际拨号代码)。格式化,验证和占位符仍然有效。然后您可以使用 getNumber 提取完整的国际号码 - 请参阅示例。此选项现在默认为 true,并且建议您保留该选项,因为它为用户提供了更好的体验。

      onlyCountries

      类型:Array 默认值:undefined 在下拉列表中,仅显示您指定的国家 / 地区 - 请参阅示例。

      placeholderNumberType

      类型:String 默认值:“MOBILE” 指定全局枚举中的一个键,intlTelInputUtils.numberType 例如"FIXED_LINE”,设置用于占位符的数字类型。

      preferredCountries

      类型:Array 默认:[“us”, “gb”] 指定要显示在列表顶部的国家 / 地区。

      preventInvalidNumbers[ REMOVED]

      防止用户输入无效字符。不幸的是,由于此处列出的原因,必须将其删除:#79 将输入字符限制为格式化字符串长度。

      separateDialCode

      类型:Boolean 默认:false 显示所选标志旁边的国家 / 地区拨号代码,因此它不是键入的号码的一部分。请注意,这将禁用,nationalMode 因为从技术上讲,我们正在处理国际号码,但拨号代码已分开。

      utilsScript

      类型:String 默认值:““示例:“build/js/utils.js” 通过指定包含的 utils.js 脚本的 URL(或者只是将其指向 cdnjs.com 上的文件)启用格式化 / 验证等。页面加载完成后(在窗口加载事件上)获取脚本以防止阻塞(脚本为~215KB)。在实例化插件时,如果定义了 Promise 对象,则会在 promiseinstance 属性下返回其中一个,因此您可以执行类似的操作,iti.promise.then(callback) 以了解此类初始化请求何时完成。有关更多信息,请参见实用程序脚本请注意,如果您懒得加载插件脚本本身(intlTelInput.js),这将无效,您将需要使用该 loadUtils 方法。

      公共方法

      在这些示例中,iti 指的是在初始化插件时返回的插件实例,例如 var iti = intlTelInput(input)

      destroy

      从输入中删除插件,并取消绑定任何事件侦听器。

      iti.destroy();
      

      getExtension 从当前号码获取扩展名。需要 utilsScript 选项。

      var extension = iti.getExtension();
      

      返回一个字符串,例如,如果输入值是”(702) 555-5555 ext. 1234”,则返回"1234"

      getNumber 以给定格式获取当前数字(默认为 E.164 标准)。枚举中提供了不同的格式 intlTelInputUtils.numberFormat- 您可以在此处看到。需要 utilsScript 选项。请注意,即使 nationalMode 已启用,仍可返回完整的国际号码。另请注意,此方法需要有效数字,因此只应在验证后使用。

      var number = iti.getNumber();
      // or
      var number = iti.getNumber(intlTelInputUtils.numberFormat.E164);
      

      返回一个字符串,例如 “+17024181234”

      getNumberType 获取当前号码的类型(固定电话 / 移动电话 / 免费电话等)。需要 utilsScript 选项。

      var numberType = iti.getNumberType();
      
      

      返回一个整数,您可以将其与全局枚举中的各种选项进行匹配,intlTelInputUtils.numberType 例如

      if (numberType === intlTelInputUtils.numberType.MOBILE) {
          // is a mobile number
      }
      
      

      请注意,在美国,没有办法区分固定电话号码和手机号码,因此它将返回 FIXED_LINE_OR_MOBILE。

      getSelectedCountryData 获取当前所选标志的国家 / 地区数据。

      var countryData = iti.getSelectedCountryData();
      
      

      返回如下内容:

      {
        name: "Afghanistan (‫افغانستان‬‎)",
        iso2: "af",
        dialCode: "93"
      }
      

      getValidationError 获取有关验证错误的更多信息。需要 utilsScript 选项。

      var error = iti.getValidationError();
      
      

      返回一个整数,您可以将其与全局枚举中的各种选项进行匹配,intlTelInputUtils.validationError 例如

      if (error === intlTelInputUtils.validationError.TOO_SHORT) {
          // the number is too short
      }
      

      isValidNumber

      验证当前数字 - 参见示例。期望国际格式化的数字(除非 nationalMode 已启用)。如果验证失败,您可以使用 getValidationError 获取更多信息。需要 utilsScript 选项。另请参阅 getNumberType 您是否要确保用户输入某种类型的号码,例如手机号码。

      var isValid = iti.isValidNumber();
      

      返回:true/false

      setCountry

      更改国家 / 地区选择(例如,当用户输入其地址时)。

      iti.setCountry("gb");
      
      

      setNumber

      插入一个数字,并相应地更新所选标志。请注意,如果 formatOnDisplay 启用,则会尝试根据 nationalMode 选项格式化数字。

      iti.setNumber("+447733123456");
      
      

      setPlaceholderNumberType

      更改 placeholderNumberType 选项。

      iti.setPlaceholderNumberType("FIXED_LINE");
      
      

      静态方法

      getCountryData

      获取所有插件的国家 / 地区数据 - 要么在其他地方重复使用,例如填充国家 / 地区下拉列表 - 请参阅示例,要么修改 - 请参阅示例。请注意,必须在初始化插件之前进行任何修改。

      var countryData = window.intlTelInputGlobals.getCountryData();
      
      

      返回国家 / 地区对象的数组:

      [{
        name: "Afghanistan (‫افغانستان‬‎)",
        iso2: "af",
        dialCode: "93"
      }, ...]
      
      

      getInstance

      初始化插件后,只需传入相关的输入元素,就可以使用此方法再次访问实例。

      var input = document.querySelector('#phone');
      var iti = window.intlTelInputGlobals.getInstance(input);
      iti.isValidNumber(); // etc
      
      

      loadUtils

      注意:只有在您加载插件脚本本身(intlTelInput.js)时才需要这样做。如果没有,那么只需使用该 utilsScript 选项。 加载 utils.js 脚本(包含在 lib 目录中)以启用格式化 / 验证等。有关详细信息,请参阅“ 实用程序脚本 ”。此方法每页只应调用一次。如果定义了 Promise 对象,则返回其中一个,这样您就可以。then(callback) 知道它何时完成。

      window.intlTelInputGlobals.loadUtils("build/js/utils.js");
      
      

      setCountryData[ REMOVED]

      设置插件的国家 / 地区数据。这个方法被删除了,因为使用 getCountryData 然后修改它(参见示例)更有意义,而不必自己生成整个事物 - 国家数据变得越来越复杂,对于每个国家我们现在有五个属性:名称,iso2 国家代码,国际拨号代码,优先权(如果两个国家 / 地区具有相同的国际拨号代码),最后是该国家 / 地区使用的区号代码列表 - 有关详细信息,请参阅 data.js。

      活动

      您可以在输入上侦听以下事件。

      countrychange 当用户从下拉列表中选择一个国家 / 地区时触发。

      input.addEventListener("countrychange", function() {
        // do something with iti.getSelectedCountryData()
      });
      

      在此处查看示例:国家 / 地区同步

      open:countrydropdown 当用户打开下拉列表时触发。

      close:countrydropdown 当用户关闭下拉列表时触发。

      实用工具脚本

      实用程序脚本(build / js / utils.js)是 Google 的 libphonenumber 的自定义构建,它具有以下功能:

      • 初始化时格式化,以及 getNumber 和 setNumber
      • 与验证 isValidNumber,getNumberType 以及 getValidationError 方法
      • 占位符设置为所选国家 / 地区的示例编号 - 甚至使用该 placeholderNumberType 选项指定编号类型(例如移动设备)
      • getNumber 即使使用该 nationalMode 选项,也可以提取标准化(E.164)国际号码

      国际号码格式 / 验证很难(因国家 / 地区而异,我们目前支持~230 个国家 / 地区)。我发现的唯一全面的解决方案是 libphonenumber,我已经将相关部分预编译成单个 JavaScript 文件并包含在构建目录中。不幸的是,即使在缩小之后它仍然是~215KB,但是如果你使用该 utilsScript 选项,那么它将仅在页面加载完成时获取脚本(以防止阻塞)。如果不考虑大小,那么您可以自己手动包含脚本,只要在初始化插件之前已经加载了它,那么它应该可以正常工作。

      要自己重新编译 utils 脚本(例如,要更新它构建的 libphonenumber 版本),请参阅参考指南。

      故障排除

      全宽输入

      如果您希望输入为全宽,则需要将容器设置为相同,即

      .intl-tel-input { width: 100%; }
      
      

      dropdownContainer:滚动下拉不关闭

      如果你有一个滚动容器而不是 window 通过不关闭滚动下拉列表导致问题,只需在该元素上侦听滚动事件,然后触发滚动事件 window,然后关闭下拉,例如

      scrollingElement.addEventListener("scroll", function() {
        var e = document.createEvent('Event');
        e.initEvent("scroll", true, true);
        window.dispatchEvent(e);
      });
      

      输入边距

      为了对齐,默认 CSS 强制输入的垂直边距 0px。如果需要垂直边距,则应将其添加到容器中(使用类 intl-tel-input)。

      显示错误消息

      如果错误处理代码在错误消息打开布局之前插入错误消息。相反,您必须在容器(带有类 intl-tel-input)之前插入它。

      下拉位置

      下拉列表应自动显示在输入上方 / 下方,具体取决于可用空间。为了使其正常工作,您必须在添加到 DOM 之后初始化插件。

      占位符

      为了获得自动特定于国家 / 地区的占位符,只需省略占位符属性即可

      引导输入组

      需要几个 CSS 修复才能使插件与 Bootstrap 输入组一起使用。你可以在这里看到 Codepen 。 注意:当您在输入组内单击下拉箭头(CSS 三角形)时,Mobile Safari 中当前存在一个导致崩溃的错误。最简单的解决方法是使用以下行删除 CSS 三角形:.intl-tel-input .iti-flag .arrow {border: none;}

      目录
      目录