intl-tel-input 的 Vue 3 组件完整使用指南：安装、Props、事件与实例方法

前端UI组件【免费下载链接】intl-tel-inputFor entering, formatting, and validating international telephone numbers. Available in vanilla JavaScript, or as React, Vue, Angular, and Svelte components.项目地址https://gitcode.com/gh_mirrors/in/intl-tel-input点击查看免费下载intl-tel-input/vue是 intl-tel-input 官方提供的 Vue 3 封装组件用于在 Vue 应用中实现国际电话号码的输入、格式化与校验。本文以 site/src/docs/markdown/vue_component.md 为主体结合 packages/vue 的源码实现与集成测试系统讲解组件安装、全部 Props 与事件、初始化选项的传递方式以及如何通过 ref 访问底层实例方法。读完本文你将能够把一个功能完整的国际电话输入组件集成进 Vue 3 应用并正确处理校验反馈、国家切换、受控值与运行时更新等实战问题。概览组件的定位与依赖intl-tel-input/vue是一个围绕核心库intl-tel-input的 Vue 3 薄封装。从 packages/vue/package.json 可以看到其依赖关系intl-tel-input核心库版本与组件保持同步当前为^29.5.3vue以 peerDependency 声明要求^3.0.0即只支持 Vue 3。组件的本质是一个渲染typetel输入框的 SFC内部在onMounted时调用核心库intlTelInput()完成初始化。你可以先访问 Validation 示例页 查看线上效果。安装与引入安装包npm install intl-tel-input/vue然后在代码中引入组件与样式。文档给出的最小示例为script setup import IntlTelInput from intl-tel-input/vue; import intl-tel-input/styles; /script template IntlTelInput initial-countryus :load-utils() import(intl-tel-input/utils) / /template这里有两个要点样式必须单独引入。import intl-tel-input/styles会加载核心库的 CSS对应 packages/core/src/css/intlTelInput.css不引入样式则组件不会呈现国家选择器与国旗等 UI。utils 脚本按需加载。utils约 260KB被单独拆出。上面示例通过loadUtils传入一个动态import()现代打包器会把它切分成独立的懒加载 chunk不影响首屏 bundle。如果你的应用里IntlTelInput组件本身已经是懒加载的也可以直接从intl-tel-input/vue/with-utils引入——该入口会直接把 utils 打进组件 bundle见下文「utils 的两种加载方式」。关于校验、E.164 存储、初始国家与本地化的通用建议可参阅 Best practices。Props 详解除了下面列出的组件专属 Props核心库的所有初始化选项都能直接作为 Prop 传入见「初始化选项」一节。专属 Props 的 TypeScript 定义集中在 packages/vue/src/props.tsexport interface Props { usePreciseValidation?: boolean; disabled?: boolean; readonly?: boolean; inputProps?: InputHTMLAttributes; initialValue?: string | null; modelValue?: string | null; }disabled类型boolean默认false同时设置电话输入框与所选国家按钮的disabled属性。文档特别强调应使用此 Prop 而非inputProps.disabled因为只有它能把国家按钮一并禁用。源码中该 Prop 在挂载后与运行时都会被同步见「响应式更新」一节。initial-value / initialValue类型string默认camelCaseinitialValue输入框的初始值。初始化时会根据number-display-format选项自动格式化。它只在初始化时生效——持续性的响应式更新应使用v-model。从源码看组件内部通过props.initialValue ?? 参与计算初始显示值IntlTelInput.vue并在 utils 加载完成后调用instance.setNumber(displayed.value)写入IntlTelInput.vue。input-props / inputProps类型object默认{}camelCaseinputProps透传给input元素的属性例如id、class、placeholder、required、onBlur等。示例如下取自 validation 示例IntlTelInput change-numbernumber $event change-validityisValid $event change-error-codeerrorCode $event initial-countryus :input-props{ class: form-control } search-input-classform-control /[!NOTE] 以下键被保留给组件/核心库自身使用会被忽略type、value、disabled、readonly、onInput、oninput。应改用组件 Propsdisabled、readonly与组件事件change-number、change-country等。源码中通过ignoredInputProps集合识别这些键并会发出警告IntlTelInput.vue。模板固定渲染input typetel因此type也无法被覆盖IntlTelInput.vue。另外class属性有特殊处理组件会把核心库自身添加的类如iti__tel-input与使用者传入的 class 合并后一起应用避免 Vue 接管 class 属性导致库的类丢失IntlTelInput.vue。readonly类型boolean默认false设置输入框的readonly属性同时禁用国家按钮。与disabled一样应使用此 Prop 而非inputProps.readonly。use-precise-validation / usePreciseValidation类型boolean默认falsecamelCaseusePreciseValidation默认组件使用核心库的isValidNumber做校验设为true后改用isValidNumberPrecise。源码中通过三目表达式动态选择IntlTelInput.vueconst isValid () (props.usePreciseValidation ? instance.value!.isValidNumberPrecise() : instance.value!.isValidNumber()) ?? false;v-model类型string默认undefined组件支持v-model双向绑定机制如下当绑定的值变化时通过setNumber更新输入框输入框处于聚焦状态时跳过以免打断用户输入当用户输入时通过update:modelValue事件同步回绑定值。IntlTelInput v-modelphone /不使用v-model时组件为非受控模式此时用initial-value提供起始值即可。受控模式下对聚焦状态与值去重的处理可见源码 IntlTelInput.vue只有当输入框未聚焦且新的值不同于当前规范化的号码时才调用setNumber同时避免光标跳动。完整可运行的受控示例在 controlled-value 示例。初始化选项全部以 Props 形式传递核心库的全部初始化选项国家选择器、格式化、校验、占位符、本地化等数十项都支持作为独立的 Vue Prop 传入使用 kebab-caseVue 惯用形式即可例如IntlTelInput initial-countryus /也可以使用 camelCase如initialCountry与文档中的选项名保持一致。[!NOTE] 如果你是从旧版本迁移旧的:initOptions{ initialCountry: us }写法已不再支持——请把每个选项作为独立 Prop 传入。[!NOTE] 这些 Props 在初始化时只读取一次之后修改不会再生效。需要运行时变更时请通过下一节「访问实例方法」处理例如getInstance().setSelectedCountry(gb)。源码对「只传递真实库选项」做了精巧的处理IntlTelInput.vue组件以definePropsProps SomeOptions()声明全部 PropIntlTelInput.vue以Object.keys(intlTelInput.defaults)获取所有合法选项键从原始 vnode props 中归一化出实际被父组件传入了哪些键kebab-case 转 camelCase只有「真实库选项键」且「父组件确实传入」的键才会进入初始化参数——这避免了 Vue 将未传的 Boolean Prop 强制置为false而覆盖库的默认值。Events组件事件一览所有事件均支持 kebab-case 与 camelCase 两种形式分别对应change-number与change-country等用法。事件在 IntlTelInput.vue 中以defineEmits声明。change-country / changeCountry类型(iso2: string) void当选中国家变化时触发参数为新国家的 iso2 代码如gb未选择国家时为。源码在updateCountry中读取instance.getSelectedCountry()?.iso2并通过lastEmittedCountry去重后发出IntlTelInput.vue。change-error-code / changeErrorCode类型(errorCode: ValidationError | null) void当号码校验错误码变化时触发参数为ValidationError字符串号码有效时为null。把错误码转换为用户可读消息的做法见 Show a user-facing error message。需要 utils 脚本已加载。change-number / changeNumber类型(number: string) void当号码变化时触发参数为标准化后的 E.164 格式号码如447700900123输入为空时为。需要 utils 脚本已加载。触发逻辑见 IntlTelInput.vue同时会继续触发changeValidity与update:modelValue。change-validity / changeValidity类型(isValid: boolean) void当号码有效性变化时触发参数为新的有效性布尔值。需要 utils 脚本已加载。close-country-selector / closeCountrySelector类型() void国家选择器关闭时触发。open-country-selector / openCountrySelector类型() void国家选择器打开时触发。strict-reject / strictReject类型(source: key | paste, rejectedInput: string, reason: invalid | max-length) void当strictMode拒绝或修改输入时触发。对大多数场景内置的strictRejectAnimation已提供震动/闪烁动画无需任何处理代码只有当需要自定义反馈例如解释拒绝原因的 toast时才用此事件。处理器接收三个参数描述「被拒绝了什么」以及「为什么」sourcekey按键或paste粘贴rejectedInput被拒绝或剥离的原始字符串——key时是按下那一个字符paste时是完整粘贴文本reasoninvalid输入包含不允许的字符或max-length接受输入会超出所选国家允许的最大长度。根据这些参数选择提示消息的示例if (reason max-length) msg Maximum length reached for this country; else if (source paste) msg Stripped invalid characters from pasted text; else msg Character not allowed: ${rejectedInput};源码侧组件监听核心库派发的strict:reject自定义事件并从event.detail中解构出这三个参数后重新发出IntlTelInput.vue。访问实例方法通过 ref 传入组件然后访问ref.value.instance即可调用核心库的全部实例方法setNumber、setSelectedCountry、setPlaceholderNumberType等const intlTelInputRef ref(null); // 触发某个动作时 intlTelInputRef.value?.instance?.setSelectedCountry(gb);也可以类似方式访问输入框 DOM 元素ref.value?.input。组件通过defineExpose({ instance, input })暴露这两者IntlTelInput.vue集成测试也验证了这一点tests/integration/vue/IntlTelInput.test.ts。实现细节instance使用shallowRef而非普通ref因为 Vue 的响应式 Proxy 会破坏Iti实例的私有字段如#ui导致实例方法调用失败IntlTelInput.vue。一个完整的运行时切换国家示例见 set-country 示例模板中绑定change-country维护状态点击按钮后调用intlTelInputRef.value?.instance?.setSelectedCountry(gb)切到英国。访问静态方法从与 Vue 组件相同的文件中具名导出核心库即可访问全部静态方法import { intlTelInput } from intl-tel-input/vue; // 注意是首字母小写的 intlTelInput之后与直接使用核心库无异例如intlTelInput.getAllCountries()等。其导出定义见 packages/vue/src/index.ts。在 validation 示例中静态对象还被用于将错误码映射为消息packages/vue/demo/validation/App.vueconst getErrorMessage (errorCode) { const { VALIDATION_ERROR } intlTelInput; switch (errorCode) { case VALIDATION_ERROR.INVALID_COUNTRY_CODE: return Invalid dial code; case VALIDATION_ERROR.TOO_SHORT: return Too short; case VALIDATION_ERROR.TOO_LONG: return Too long; default: return Invalid number; } };utils 的两种加载方式组件需要 utils 才能提供getNumber、isValidNumber、getValidationError等能力事件一节中标注「需要 utils」的即为此类。有两种加载方式懒加载推荐传入:load-utils() import(intl-tel-input/utils)utils 成为独立的懒加载 chunk直接打包从intl-tel-input/vue/with-utils引入组件初始化时 utils 已就绪。该入口在 packages/vue/src/indexWithUtils.ts 中通过intlTelInput.utils utils完成注入并由 packages/vue/package.json 的exports字段暴露./with-utils子路径。源码对「utils 尚未加载」的窗口期做了兜底如果 utils 加载前就发生了输入事件组件把更新标记为pendingUpdate待instance.promise解析后再重放该次更新确保事件不丢失IntlTelInput.vue。响应式更新与生命周期disabled / readonly通过watch监听变化时调用instance.setDisabled()/setReadonly()同步IntlTelInput.vue。完整示例见 toggle-disabled 示例按钮点击即切换:disabled。卸载清理onUnmounted中移除全部事件监听并调用instance.destroy()IntlTelInput.vue。测试验证了卸载后输入框不再被包裹tests/integration/vue/IntlTelInput.test.ts。监听顺序组件在intlTelInput()初始化之后才注册自己的input监听器确保核心库先处理原生输入事件、更新内部状态组件再读取getSelectedCountry()/getNumber()拿到最新值。这避免了change-number处理器中读到陈旧国家数据的回归问题对应测试见 tests/integration/vue/IntlTelInput.test.ts。相关示例与后续阅读线上示例Validation 示例页仓库内 demosimple、validation、set-country、controlled-value、toggle-disabled完整初始化选项Initialisation options也可在 playground 交互式尝试核心实例方法与静态方法Methods类型定义含ValidationErrorTypes通用实践建议Best practices。包内也提供了本地运行 demo 的方式见 packages/vue/README.mdnpm run vue:demo默认运行 validation 示例可用DEMOsimple npm run vue:demo切换其他示例。赞分享前端UI组件【免费下载链接】intl-tel-inputFor entering, formatting, and validating international telephone numbers. Available in vanilla JavaScript, or as React, Vue, Angular, and Svelte components.项目地址https://gitcode.com/gh_mirrors/in/intl-tel-input点击查看免费下载相关推荐intl-tel-input React 组件完全指南安装、Props、受控用法与实例方法intl tel input React 组件完全指南安装、Props、受控用法与实例方法 intl tel input/react 是 intl tel前端UI组件Svelte 5 集成 intl-tel-input 完整指南安装、Props、事件回调与实例方法Svelte 5 集成 intl tel input 完整指南安装、Props、事件回调与实例方法 本文是一份面向 Svelte 5 开发者的 intl te前端UI组件intl-tel-input Angular 组件完全指南安装、表单集成、事件与实例方法intl tel input Angular 组件完全指南安装、表单集成、事件与实例方法 intl tel input/angular 是国际电话号码输入库前端UI组件上一篇从 CHANGELOG 透视 scalar/nuxtScalar API 文档 Nuxt 模块的演进、关键修复与工程实践下一篇Easy-Vibe 系列Embedding 与向量检索原理实战指南——从文本到可检索向量的完整技术栈创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考