插件 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;}


AXIHE / 精选资源

浏览全部教程

面试题

学习网站

前端培训
自己甄别

前端书籍

关于朱安邦

我叫 朱安邦,阿西河的站长,在杭州。

以前是一名平面设计师,后来开始接接触前端开发,主要研究前端技术中的JS方向。

业余时间我喜欢分享和交流自己的技术,欢迎大家关注我的 Bilibili

关注我: Github / 知乎

目前重心已经放在研究区块链上面了

我叫朱安邦,阿西河的站长

目前在杭州从事区块链周边的开发工作,机械专业,以前从事平面设计工作。

2014年底脱产在老家自学6个月的前端技术,自学期间几乎从未出过家门,最终找到了满意的前端工作。更多>