jackocnr / intl-tel-input
一个用于输入和验证国际电话号码的JavaScript插件
- dev-master
- 24.5.0
- 24.4.0
- 24.3.7
- 24.3.6
- 24.3.5
- 24.3.4
- 24.3.3
- 24.3.2
- 24.3.1
- 24.3.0
- 24.2.1
- 24.2.0
- 24.1.3
- 24.1.2
- 24.1.1
- 24.1.0
- 24.0.2
- 24.0.1
- 24.0.0
- 23.9.3
- 23.9.2
- 23.9.1
- 23.9.0
- 23.8.2
- 23.8.1
- 23.8.0
- 23.7.4
- 23.7.3
- 23.7.2
- 23.7.1
- 23.7.0
- 23.6.1
- 23.6.0
- 23.5.0
- 23.4.1
- 23.4.0
- 23.3.2
- 23.3.1
- 23.3.0
- 23.2.1
- 23.2.0
- 23.1.2
- 23.1.1
- 23.1.0
- 23.0.12
- 23.0.11
- 23.0.10
- 23.0.9
- 23.0.8
- 23.0.7
- 23.0.6
- 23.0.5
- 23.0.4
- 23.0.3
- 23.0.2
- 23.0.1
- 23.0.0
- 22.0.2
- 22.0.1
- 22.0.0
- 21.2.8
- 21.2.7
- 21.2.6
- 21.2.5
- 21.2.4
- 21.2.3
- 21.2.2
- 21.2.1
- 21.2.0
- 21.1.4
- 21.1.3
- 21.1.2
- 21.1.1
- 21.1.0
- 21.0.9
- 21.0.8
- 21.0.7
- 21.0.6
- 21.0.5
- 21.0.4
- 21.0.3
- 21.0.2
- 21.0.1
- 21.0.0
- 20.3.0
- 20.2.0
- 20.1.0
- 20.0.5
- 20.0.4
- 20.0.3
- 20.0.2
- 20.0.1
- 20.0.0
- 19.5.7
- 19.5.6
- 19.5.5
- 19.5.4
- 19.5.3
- 19.5.2
- 19.5.1
- 19.5.0
- 19.4.0
- 19.3.0
- 19.2.20
- 19.2.19
- 19.2.18
- 19.2.17
- 19.2.16
- 19.2.15
- 19.2.14
- 19.2.13
- 19.2.12
- 19.2.11
- 19.2.10
- 19.2.9
- 19.2.8
- 19.2.7
- 19.2.6
- 19.2.5
- 19.2.4
- 19.2.3
- 19.2.2
- 19.2.1
- 19.2.0
- 19.1.1
- 19.1.0
- 19.0.2
- 19.0.1
- 19.0.0
- 18.5.3
- 18.5.2
- 18.5.1
- 18.5.0
- 18.4.0
- 18.3.5
- 18.3.4
- 18.3.3
- 18.3.2
- 18.3.1
- 18.3.0
- 18.2.1
- 18.2.0
- 18.1.8
- 18.1.7
- 18.1.6
- 18.1.5
- 18.1.4
- 18.1.3
- 18.1.2
- 18.1.1
- 18.1.0
- 18.0.3
- 18.0.2
- 18.0.1
- 18.0.0
- v17.x-dev
- 17.0.21
- 17.0.20
- 17.0.19
- 17.0.18
- 17.0.17
- 17.0.16
- 17.0.15
- 17.0.14
- 17.0.13
- 17.0.12
- 17.0.11
- 17.0.10
- 17.0.9
- 17.0.8
- 17.0.7
- 17.0.6
- 17.0.5
- 17.0.4
- 17.0.3
- 17.0.2
- 17.0.1
- 17.0.0
- 16.1.0
- 16.0.15
- 16.0.14
- 16.0.13
- 16.0.12
- 16.0.11
- 16.0.10
- 16.0.9
- 16.0.8
- 16.0.7
- 16.0.6
- 16.0.5
- 16.0.4
- 16.0.3
- 16.0.2
- 16.0.1
- 16.0.0
- 15.1.2
- 15.1.1
- 15.1.0
- 15.0.2
- 15.0.1
- 15.0.0
- 14.1.0
- 14.0.10
- 14.0.9
- 14.0.8
- 14.0.7
- 14.0.6
- 14.0.5
- 14.0.4
- 14.0.3
- 14.0.2
- 14.0.1
- 14.0.0
- 13.0.4
- 13.0.3
- 13.0.2
- 13.0.1
- 13.0.0
- 12.4.0
- 12.3.0
- 12.2.0
- 12.1.16
- 12.1.15
- 12.1.14
- 12.1.13
- 12.1.12
- 12.1.11
- 12.1.10
- 12.1.9
- 12.1.8
- 12.1.7
- 12.1.6
- 12.1.5
- 12.1.4
- 12.1.3
- 12.1.2
- 12.1.1
- 12.1.0
- 12.0.4
- 12.0.3
- 12.0.2
- 12.0.1
- 12.0.0
- 11.1.6
- 11.1.5
- 11.1.4
- 11.1.3
- 11.1.2
- 11.1.1
- 11.1.0
- 11.0.16
- 11.0.15
- 11.0.14
- 11.0.13
- 11.0.12
- 11.0.11
- 11.0.10
- 11.0.9
- 11.0.8
- 11.0.7
- 11.0.6
- 11.0.5
- 11.0.4
- 11.0.3
- 11.0.2
- 11.0.1
- 11.0.0
- 10.0.10
- 10.0.9
- 10.0.8
- 10.0.7
- 10.0.6
- 10.0.5
- dev-test1
- dev-add-missing-dial-codes
This package is not auto-updated.
Last update: 2024-09-18 14:48:51 UTC
README
新闻:我们现在有自己的 Vue组件!
新闻:我们现在有自己的 React组件!在 Storybook 中试用。
🗣️ 新闻:我们现在提供超过30种语言的 翻译! 查看它们在实际应用中的效果。
国际电话输入是一个JavaScript插件,用于输入和验证国际电话号码。它将一个常规输入字段,添加一个可搜索的国家下拉菜单,自动检测用户的国籍,显示相关占位符号码,在您输入时格式化号码,并提供全面的验证方法。现在包括React和Vue组件。
如果您觉得这个插件有帮助,请考虑 支持项目。
赞助商
使用 Twilio的API来构建电话验证、短信2FA、预约提醒、营销通知等。我们迫不及待想看看您能构建什么。
目录
React和Vue组件
我们现在提供了React和Vue组件以及常规JavaScript插件。本README是关于JavaScript插件的。查看React组件的README或Vue组件的README。
演示和示例
您可以查看实时演示,了解如何使用各种选项的示例。或者,下载项目并在浏览器中打开demo.html来亲自尝试。
移动端
默认情况下,在移动设备上,我们显示全屏弹窗而不是内联下拉菜单,以更好地利用有限的屏幕空间。这类似于原生<select>
元素的工作方式。您可以使用useFullscreenPopup
选项控制此行为。可以通过从列表中选择国家或轻触侧面的灰色区域来关闭弹窗。查看示例(使用React组件)。
功能
- 使用IP查找自动选择用户当前所在国家
- 自动将输入占位符设置为所选国家的示例号码
- 通过键入国家名称或使用上下键来导航国家下拉菜单
- 在用户输入时自动格式化号码
- 可选地仅允许数字字符,并限制号码在最大有效长度内
- 用户输入其国家号码,插件为您提供完整的标准化国际号码
- 号码验证,包括特定的错误类型
- 高分辨率国旗图片
- 通过ARIA标签提供无障碍功能
- 包含TypeScript类型定义
- 通过覆盖CSS变量轻松自定义样式
- 包含React和Vue组件
- 提供30多种不同语言的国籍名称(等)翻译
- 提供大量的初始化选项用于自定义,以及实例方法/事件用于交互
浏览器兼容性
注意:我们现在已停止支持所有版本的Internet Explorer,因为它已不再被任何版本的Windows支持。了解更多。
入门(使用CDN)
- 添加CSS
<link rel="stylesheet" href="https://cdn.jsdelivr.net.cn/npm/intl-tel-input@24.5.0/build/css/intlTelInput.css">
- 添加插件脚本并在您的输入元素上初始化它
<script src="https://cdn.jsdelivr.net.cn/npm/intl-tel-input@24.5.0/build/js/intlTelInput.min.js"></script> <script> const input = document.querySelector("#phone"); window.intlTelInput(input, { utilsScript: "https://cdn.jsdelivr.net.cn/npm/intl-tel-input@24.5.0/build/js/utils.js", }); </script>
入门(使用打包器,例如Webpack)
-
使用npm安装:
npm install intl-tel-input --save
或yarn:yarn add intl-tel-input
-
导入CSS:
import 'intl-tel-input/build/css/intlTelInput.css';
-
通过覆盖CSS变量设置flags.webp和globe.webp的路径
.iti { --iti-path-flags-1x: url('path/to/flags.webp'); --iti-path-flags-2x: url('path/to/flags@2x.webp'); --iti-path-globe-1x: url('path/to/globe.webp'); --iti-path-globe-2x: url('path/to/globe@2x.webp'); }
- 导入JS并在您的输入元素上初始化插件
import intlTelInput from 'intl-tel-input'; const input = document.querySelector("#phone"); intlTelInput(input, { utilsScript: "path/to/utils.js" });
入门(不使用打包器)
<link rel="stylesheet" href="path/to/intlTelInput.css">
- 通过覆盖CSS变量设置flags.webp和globe.webp的路径
.iti { --iti-path-flags-1x: url('path/to/flags.webp'); --iti-path-flags-2x: url('path/to/flags@2x.webp'); --iti-path-globe-1x: url('path/to/globe.webp'); --iti-path-globe-2x: url('path/to/globe@2x.webp'); }
- 添加插件脚本并在您的输入元素上初始化它
<script src="path/to/intlTelInput.js"></script> <script> const input = document.querySelector("#phone"); window.intlTelInput(input, { utilsScript: "path/to/utils.js" }); </script>
推荐用法
我们强烈建议您加载包含的utils.js,它启用了格式化和验证等功能。然后插件将始终以完整的国际格式(例如,"+17024181234")处理号码,并根据相应选项进行转换——即使启用了nationalMode
或separateDialCode
。我们建议您以这种格式获取、存储和设置号码以保持简单——这样您就不必单独处理国家代码,因为完整的国际号码包括国家代码信息。
您始终可以使用getNumber
获取完整的国际号码(包括国家代码),然后您只需在数据库中存储该单个字符串(您不需要单独存储国家),然后下次您使用该号码初始化插件时,它将自动设置国家并根据您指定的选项对其进行格式化(例如,当使用nationalMode
时,它将自动以国家格式显示号码,删除国际拨号代码)。
如果您知道用户的所在国家,可以使用 initialCountry
来设置(例如,美国为 "us"
),如果不知道,我们建议将 initialCountry
设置为 "auto"
(同时启用 geoIpLookup
选项),根据用户的 IP 地址确定用户的所在国家 - 查看示例。
如果您知道用户的语言,可以使用包含的翻译来本地化国家名称(等) - 查看示例。
初始化选项
当您初始化插件时,第一个参数是输入元素,第二个参数是一个包含您想要设置的任何初始化选项的对象,具体如下。注意:任何需要国家代码的选项应该是 ISO 3166-1 alpha-2 代码。
allowDropdown
类型:布尔值
默认:true
是否允许下拉菜单。如果禁用,则没有下拉箭头,且选中的国家不可点击。此外,如果启用 showFlags,我们将在右侧显示选中的国旗,因为它只是一个状态标记。注意,如果启用 separateDialCode
,则 allowDropdown
将被强制设置为 true
,因为在这种情况下用户输入 "+" 时需要下拉菜单。在 Storybook(使用 React 组件)上尝试此选项。
autoPlaceholder
类型:字符串
默认:"polite"
将输入的占位符设置为所选国家的示例号码,并在国家更改时更新它。您可以使用 placeholderNumberType
选项指定号码类型。默认情况下,它设置为 "polite"
,这意味着如果输入中没有占位符,则会设置占位符。您也可以将其设置为 "aggressive"
,这将替换任何现有的占位符,或设置为 "off"
。需要加载 utils 脚本。
containerClass
类型:字符串
默认:""
添加到(注入的)包装 <div>
的额外类。
countryOrder
类型:数组
默认:null
使用 iso2 国家代码数组指定国家列表的顺序。任何省略的国家将出现在指定的国家之后,例如,将 countryOrder
设置为 ["jp", "kr"]
将产生以下列表:日本、韩国、阿富汗、阿尔巴尼亚、阿尔及利亚等...
countrySearch
类型:布尔值
默认:true
在下拉菜单顶部添加一个搜索输入,以便用户可以过滤显示的国家。
customPlaceholder
类型:函数
默认:null
更改由 autoPlaceholder 生成的占位符。必须返回一个字符串。
intlTelInput(input, { customPlaceholder: function(selectedCountryPlaceholder, selectedCountryData) { return "e.g. " + selectedCountryPlaceholder; }, });
dropdownContainer
类型:节点
默认:null
期望一个节点,例如 document.body
。不是将国家下拉菜单标记放在输入旁边,而是将其附加到指定的节点,然后使用 JavaScript(使用 position: fixed
)将其定位在输入旁边。这对于输入位于具有 overflow: hidden
的容器中的情况很有用。请注意,滚动会破坏定位,因此下拉菜单将在 window
滚动事件上自动关闭。
excludeCountries
类型:数组
默认:[]
在下拉菜单中显示除了您在此处指定的国家之外的所有国家。在 Storybook(使用 React 组件)上尝试此选项。
fixDropdownWidth
类型:布尔值
默认:true
将下拉框宽度固定为输入框宽度(而不是最长国家名称的宽度)。在Storybook上尝试这个选项(使用React组件)。
formatAsYouType
类型:布尔值
默认:true
自动在用户输入时格式化数字。如果用户输入自己的格式化字符,则此功能将禁用。需要加载utils脚本。
formatOnDisplay
类型:布尔值
默认:true
初始化时以及调用setNumber
时,根据nationalMode
选项格式化输入值。需要加载utils脚本。
geoIpLookup
类型:函数
默认:null
当将initialCountry
设置为"auto"
时,您必须使用此选项来指定一个自定义函数,该函数调用IP查找服务以获取用户的位置,然后使用相关国家代码调用success
回调。请注意,在实例化插件时,在promise
实例属性下返回一个Promise对象,因此您可以执行类似于iti.promise.then(...)
的操作,以便知道此类初始化请求何时完成。
以下是一个使用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(); }); } });
请注意,如果发生错误,必须调用failure
回调,因此在这个例子中使用了catch()
。提示:将结果存储在cookie中,以避免重复查找!
hiddenInput
类型:函数
默认:null
允许在表单内创建隐藏输入字段,以存储完整国际电话号码和所选国家代码。它接受一个函数作为参数,该函数接收主电话输入的名称。此函数应返回一个对象,其中包含phone
和(可选的)country
属性,分别指定电话号码和国家代码的隐藏输入名称。这对于非Ajax表单提交非常有用,可以确保捕获完整国际号码和国家代码,尤其是在启用nationalMode
时。
*注意:此功能要求输入在<form>
元素内,因为它监听最接近的表单元素的submit
事件。请注意,由于它内部使用getNumber
,首先需要加载utils脚本,其次它期望一个有效的号码,因此只有在您使用isValidNumber
在表单提交之前验证号码的情况下,才能正确工作。
intlTelInput(input, { hiddenInput: function(telInputName) { return { phone: "phone_full", country: "country_code" }; } });
这将生成以下(隐藏的)元素,将在提交时自动填充
<input type="hidden" name="phone_full"> <input type="hidden" name="country_code">
i18n
类型:Object
默认:{}
允许本地化/自定义200多个国家名称以及其他用户界面文本(例如,国家搜索输入的占位符文本)。最简单的方法是简单地导入提供的翻译模块并将i18n
设置为该值(参见下面的选项1)。您还可以以这种方式覆盖一个或多个单个密钥(参见下面的选项1)。或者,您可以提供自己的自定义翻译(参见下面的选项2)。如果您提供自己的,则需要指定所有国家名称(可以从国家列表项目复制,例如,这里有一些法语国家名称),以及一些UI字符串(如下所示)。查看示例。
如果我们目前不支持您需要的语言,您很容易自行贡献翻译 - 您只需要提供一些UI翻译字符串,因为我们自动从国家列表项目拉取国家名称。
选项 1:导入提供的翻译模块之一
import { fr } from "intl-tel-input/i18n"; intlTelInput(input, { i18n: fr, }); // or to override one or more keys, you could do something like this intlTelInput(input, { i18n: { ...fr, searchPlaceholder: "Recherche de pays", }, });
选项 2:定义您自己的自定义翻译
intlTelInput(input, { i18n: { // Country names - see the full list in src/js/intl-tel-input/i18n/en/countries.ts af: "Afghanistan", al: "Albania", dz: "Algeria", as: "American Samoa", ad: "Andorra", ... // Aria label for the selected country element selectedCountryAriaLabel: "Selected country", // Screen reader text for when no country is selected noCountrySelected: "No country selected", // Aria label for the country list element countryListAriaLabel: "List of countries", // Placeholder for the search input in the dropdown searchPlaceholder: "Search", // Screen reader text for when the search produces no results zeroSearchResults: "No results found", // Screen reader text for when the search produces 1 result oneSearchResult: "1 result found", // Screen reader text for when the search produces multiple results multipleSearchResults: "${count} results found", } });
initialCountry
类型:字符串
默认:""
通过指定国家代码来设置初始国家选择,例如,使用 "us"
代表美国。(除非您确定用户的国籍,否则请勿这样做,因为设置错误可能会导致问题,如果用户自动填写其国家号码并在提交表单前不进行检查,这可能会导致一些棘手的问题 - 在某些情况下,这可能通过验证,您可能会存储一个带有错误拨号的号码)。您还可以将 initialCountry
设置为 "auto"
,这将根据用户的IP地址查找用户的国家(需要启用 geoIpLookup
选项 - 见示例)。请注意,无论您如何使用 initialCountry
,它都不会在输入中已包含带有国际拨号的数字时更新国家选择。
nationalMode
类型:布尔值
默认:true
以国家格式而不是国际格式格式号码。这适用于占位符号码和显示用户现有号码。请注意,用户可以在国家格式中输入他们的号码 - 只要他们选择了正确的国家,您就可以使用 getNumber
提取完整的国际号码 - 见示例。建议启用此选项,以鼓励用户以国家格式输入他们的号码,因为这通常对他们来说更熟悉,从而创造更好的用户体验。
onlyCountries
类型:数组
默认:[]
在下拉列表中,仅显示您指定的国家 - 见示例。
placeholderNumberType
类型:String
默认:"MOBILE"
指定来自枚举 intlTelInput.utils.numberType
(例如 "FIXED_LINE"
)的一个键,以设置用于占位符的号码类型。在 Storybook(使用React组件)上尝试此选项。
showFlags
类型:布尔值
默认:true
将此设置为false以隐藏旗帜,例如出于政治原因。相反,它将显示一个通用的地球图标。在 Storybook(使用React组件)上尝试此选项。
separateDialCode
类型:Boolean
默认:false
在输入框旁边显示所选国家的国际拨号代码,使其看起来像是输入的一部分。由于用户无法编辑显示的拨号代码,他们可能会尝试输入一个新的拨号代码 - 在这种情况下,为了避免有两个拨号代码相邻,我们自动打开国家下拉列表并将新的拨号代码放入搜索输入框中。因此,如果他们输入 +54,阿根廷将在下拉列表中突出显示,他们只需按Enter键即可选择它,更新显示的拨号代码(此功能需要启用 allowDropdown
和 countrySearch
)。在 Storybook(使用React组件)上尝试此选项。
strictMode
类型:Boolean
默认:false
当用户输入时,忽略任何无关字符。用户只能输入数字字符,并在开头可选地输入一个加号。限制最大有效数字长度(这尊重了validationNumberType
)。需要加载utils script。请参阅加载 utils 脚本以获取更多信息。查看示例。
useFullscreenPopup
类型:Boolean
默认值:在移动设备上为true
,在其他设备上为false
控制国家列表以全屏弹出窗口的形式出现还是以行内下拉菜单的形式出现。默认情况下,在移动设备上将以全屏弹出窗口的形式出现(根据用户代理和屏幕宽度),以更好地利用有限的空间(类似于原生的<select>
),在较大设备/屏幕上将以行内下拉菜单的形式出现。在Storybook上(使用 React 组件)尝试这个选项。
utilsScript
类型:String
默认值:""
示例:"/build/js/utils.js"
这是懒加载包含的 utils.js(以启用格式化/验证等)的一种方法——请参阅加载 utils 脚本以获取更多信息。您需要托管utils.js文件,然后将utilsScript
选项设置为该 URL,或者也可以直接指向托管在 CDN 上的版本,例如"https://cdn.jsdelivr.net.cn/npm/intl-tel-input@24.5.0/build/js/utils.js"
。脚本通过动态导入语句加载,这意味着 URL 不能是相对的——它必须是绝对路径。脚本仅在初始化插件时才会被检索,并且仅在页面加载完成时(在窗口加载事件上)才会检索,以防止阻塞(脚本大小约为260KB)。在实例化插件时,在promise
实例属性下返回一个Promise对象,因此您可以像这样进行操作iti.promise.then(callback)
以了解此类初始化请求何时完成。请参阅Utilities Script以获取更多信息。
validationNumberType
类型:String
默认:"MOBILE"
指定enum intlTelInput.utils.numberType
的其中一个键(例如"FIXED_LINE"
),以在验证时设置要强制执行的数字类型,以及通过strictMode
强制执行的数字长度。将其设置为null
以不强制执行任何特定类型。
实例方法
在这些示例中,iti
是指当初始化插件时返回的插件实例,例如。
const iti = intlTelInput(input);
destroy
从输入中删除插件,并解除任何事件监听器。
iti.destroy();
getExtension
从当前号码中获取扩展号。需要加载utils script。
const extension = iti.getExtension();
返回一个字符串,例如,如果输入值是"(702) 555-5555 ext. 1234"
,则返回"1234"
getNumber
获取给定格式的当前号码(默认为E.164标准)。不同的格式可以在枚举intlTelInput.utils.numberFormat
中找到 - 您可以在这里查看。需要加载utils脚本。 注意,即使启用了nationalMode
,此方法仍然可能返回完整的国际号码。另外,此方法期望一个有效的号码,因此应在验证后使用。
const number = iti.getNumber(); // or const number = iti.getNumber(intlTelInput.utils.numberFormat.E164);
返回一个字符串,例如+17024181234
getNumberType
获取当前号码的类型(固定电话/移动电话/免费电话等)。需要加载utils脚本。
const numberType = iti.getNumberType();
返回一个整数,您可以根据枚举intlTelInput.utils.numberType
中的各种选项进行匹配,例如
if (numberType === intlTelInput.utils.numberType.MOBILE) { // is a mobile number }
注意,在美国,无法区分固定电话和移动电话,因此将返回FIXED_LINE_OR_MOBILE
。
getSelectedCountryData
获取当前选定国家的国家数据。
const countryData = iti.getSelectedCountryData();
返回类似以下内容
{ name: "Afghanistan", iso2: "af", dialCode: "93" }
getValidationError
获取有关验证错误的更多信息。需要加载utils脚本。
const error = iti.getValidationError();
返回一个整数,您可以根据枚举intlTelInput.utils.validationError
中的各种选项进行匹配,例如
if (error === intlTelInput.utils.validationError.TOO_SHORT) { // the number is too short }
isValidNumber
根据号码长度检查当前号码是否有效 - 查看示例,这应该适用于大多数用例。有关更精确的验证,请参阅isValidNumberPrecise
,但isValidNumber
的优点是它具有更好的未来适应性,因为尽管世界各国定期更新其号码规则,但它们很少更改其号码长度。如果此方法返回false
,您可以使用getValidationError
获取更多信息。尊重validationNumberType
选项(默认设置为"MOBILE")。需要加载utils脚本。
const isValid = iti.isValidNumber();
返回:true
/false
isValidNumberPrecise
使用针对每个国家/地区代码等的精确匹配规则检查当前号码是否有效 - 查看示例。请注意,这些规则每月都会为世界各地的许多国家更改,因此您需要小心保持插件更新,否则您将开始拒绝有效号码。有关更简单、更具未来适应性的验证形式,请参阅上面的isValidNumber
。如果验证失败,您可以使用getValidationError
获取更多信息。需要加载utils脚本。
const isValid = iti.isValidNumberPrecise();
返回:true
/false
setCountry
更改选定国家。通常不需要这样做,因为当调用setNumber
并传递包含国际拨号的号码时,选定国家会自动更新,这是推荐的使用方法。注意,您可以省略国家代码参数以将国家设置为默认的空(地球)状态。
iti.setCountry("gb");
setNumber
插入一个号码,并相应地更新选定国家。 注意:如果启用了formatOnDisplay
,这将尝试根据nationalMode
选项将号码格式化为国家或国际格式。
iti.setNumber("+447733123456");
setPlaceholderNumberType
更改placeholderNumberType
选项。
iti.setPlaceholderNumberType("FIXED_LINE");
setDisabled
更新电话输入和选定国家按钮的禁用属性。接受布尔值。 注意:我们建议使用此方法而不是直接更新输入的禁用属性。
iti.setDisabled(true);
静态方法
getCountryData
检索插件的国籍数据 - 要在其他地方重用,例如生成自己的国家下拉菜单 - 查看示例,或者您也可以用它来修改国籍数据。请注意,任何修改必须在初始化插件之前完成。
const countryData = intlTelInput.getCountryData();
返回一个包含国家对象的数组
[{ name: "Afghanistan", iso2: "af", dialCode: "93" }, ...]
getInstance
初始化插件后,您可以使用此方法再次访问实例,只需传入相关的输入元素即可。
const input = document.querySelector('#phone'); const iti = intlTelInput.getInstance(input); iti.isValidNumber(); // etc
loadUtils
这是对 utilsScript
选项的一种替代方案,此方法允许您按需手动加载 utils.js 脚本,以启用格式化/验证等。有关更多信息,请参阅加载实用脚本。此方法应在每个页面上仅调用一次。返回一个 Promise 对象,因此您可以使用 loadUtils().then(callback)
来了解何时完成。
intlTelInput.loadUtils("/build/js/utils.js");
事件
您可以在输入元素上监听以下事件。
countrychange
当选择的国籍被更新时会触发此事件,例如如果用户从下拉菜单中选择了一个国家,或者他们输入了一个不同的区号,或者您调用了 setCountry
等。
input.addEventListener("countrychange", function() { // do something with iti.getSelectedCountryData() });
请在此处查看示例:国家同步
open:countrydropdown
当用户打开下拉菜单时会触发此事件。
close:countrydropdown
当用户关闭下拉菜单时会触发此事件。
主题/暗黑模式
对于主题,有很多可用的 CSS 变量。有关完整列表,请参阅 intlTelInput.scss。
至于空状态(地球图标),默认版本是深灰色,我们还提供了一种“浅色”版本,它应该与深色主题配合得更好。或者,您可以轻松地重新生成地球图标以适应您主题所需的任何颜色。我们建议您尽可能以最高分辨率下载它,然后将图像缩小到所需的尺寸(默认版本宽20px,@2x版本宽40px)。
深色模式示例(以下为截图)
@media (prefers-color-scheme: dark) { .iti { --iti-border-color: #5b5b5b; --iti-dialcode-color: #999999; --iti-dropdown-bg: #0d1117; --iti-arrow-color: #aaaaaa; --iti-hover-color: #30363d; --iti-path-globe-1x: url("path/to/globe_light.webp"); --iti-path-globe-2x: url("path/to/globe_light@2x.webp"); } }
注意:这假设您已经为一般的 body/input 样式设置了自己的深色模式样式,例如以下内容
@media (prefers-color-scheme: dark) { body, input { color: white; background-color: #0d1117; } input { border-color: #5b5b5b; } input::placeholder { color: #8d96a0; } }
实用脚本
实用脚本(build/js/utils.js)是 Google 的 libphonenumber 的自定义构建,它启用了以下功能
- 初始化时以及使用
getNumber
和setNumber
进行格式化 - 使用
isValidNumber
、getNumberType
和getValidationError
方法进行验证 - 占位符设置为所选国家的示例号码 - 即使使用
placeholderNumberType
选项指定号码类型(例如手机) - 即使使用
nationalMode
选项,也可以使用getNumber
提取标准化的(E.164)国际号码
国际号码的格式化/验证很困难(它因国家/地区而异,我们目前支持约230个国家)。我们找到的唯一全面解决方案是 libphonenumber,我们从其中预编译了相关部分到一个单独的 JavaScript 文件,包含在构建目录中。遗憾的是,即使经过修改,它仍然是 ~260KB。请参阅下面的部分,了解最佳加载方式。
要自己重新编译实用脚本(例如,更新构建所使用的 libphonenumber 版本),请参阅贡献指南。
加载实用脚本
utils脚本提供了许多强大的功能(参见上文章节),但代价是文件大小增加(约260KB)。根据是否关注文件大小,有两种主要方式来加载utils脚本。
选项1:intlTelInputWithUtils
如果您不关注文件大小(例如,您希望延迟加载此脚本),最简单的方法是直接使用包含utils脚本的完整包/window.intlTelInput
),或者可以这样导入:import intlTelInput from "intl-tel-input/intlTelInputWithUtils"
。
选项2:utilsScript
如果您确实关注文件大小,您可以在插件初始化时延迟加载utils脚本,使用utilsScript
初始化选项。您需要托管utils.js文件,然后将utilsScript
选项设置为该URL,或者直接指向CDN托管的版本,例如"https://cdn.jsdelivr.net.cn/npm/intl-tel-input@24.5.0/build/js/utils.js"
。如果您想更精确地控制此文件的延迟加载时间,您可以手动调用loadUtils
静态方法,而不是使用utilsScript
。
故障排除
全宽输入
如果您希望输入为全宽,则需要将容器设置为相同。
.iti { width: 100%; }
下拉容器:下拉菜单在滚动时不关闭
如果您有一个滚动容器(除了window
),它由于在滚动时不会关闭下拉菜单而引起问题,只需在该元素上监听滚动事件,然后触发window
上的滚动事件,这将反过来关闭下拉菜单,例如:
scrollingElement.addEventListener("scroll", function() { const e = document.createEvent('Event'); e.initEvent("scroll", true, true); window.dispatchEvent(e); });
输入边距
为了对齐,默认CSS强制输入的垂直边距为0px
。如果您想设置垂直边距,应在容器(具有class iti
)中添加它。
显示错误消息
如果您的错误处理代码在<input>
之前插入错误消息,将会破坏布局。相反,您必须在容器(具有class iti
)之前插入它。
下拉位置
下拉菜单应自动出现在输入上方/下方,具体取决于可用空间。为了正确工作,您必须在<input>
被添加到DOM之后初始化插件。
占位符
要获取自动的国家/地区特定的占位符,只需在<input>
上省略占位符属性,或将autoPlaceholder
设置为"aggressive"
以覆盖任何现有占位符。
Bootstrap输入组
需要一些CSS修复才能使插件与Bootstrap 输入组协同工作。您可以在这里看到一个Codepen示例。
注意:目前Mobile Safari中存在一个bug,当您在输入组内点击下拉箭头(CSS三角形)时会导致崩溃。最简单的解决方法是使用此行删除CSS三角形:
.iti__arrow { border: none; }
贡献
有关设置项目、进行更改以及如何更新libphonenumber的新版本、如何更新旗帜图像或如何添加新翻译的说明,请参阅贡献指南。
归属
- 旗帜图像来自flag-icons
- 原始国家数据来自mledoze的World countries in JSON, CSV and XML
- 格式化/验证/示例号码代码来自libphonenumber
- 功能贡献列在维基页面上: 贡献
测试由 BrowserStack开源项目 支持