前端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内置了覆盖全球多语言场景的本地化能力涵盖国家名称的按语言显示、界面字符串翻译、从右到左RTL布局适配以及阿拉伯-印度数字 / 波斯数字等替代数字输入。本文以 localisation.md 为核心骨架结合核心包源码与集成测试系统讲解每个本地化选项的用法、默认值与底层实现原理读完你可以直接为站点接入countryNameLocale、countryNameOverrides、uiTranslations等配置并理解 RTL 布局与替代数字在源码层面的工作方式。本地化能力总览intl-tel-input的本地化由四个维度组成分别对应独立的初始化选项国家名称本地化通过countryNameLocale指定语言通过countryNameOverrides覆盖个别国家名称UI 字符串翻译通过uiTranslations翻译搜索框占位符、无结果提示、无障碍标签等界面文案RTL 布局自动检测页面dirrtl并调整整体布局同时保持电话号码仍按 LTR 书写替代数字支持阿拉伯-印度数字与波斯数字输入并在内部归一化为 ASCII0-9用于解析校验。你可以在仓库的 Playground 中通过?uiTranslationsru#translation-options实测不同翻译效果也可以查看 Right to left 示例 的完整配置。国家名称本地化国家名称由原生Intl.DisplayNamesAPI 生成该 API 开箱即用地支持数百种语言环境。使用countryNameLocale选项指定语言标签BCP 47例如fr表示法语const iti intlTelInput(input, { countryNameLocale: fr, });该选项默认值为en见 options.ts且运行时校验要求其必须是字符串否则会被忽略并打印警告。按 iso2 覆盖个别国家名称你还可以通过countryNameOverrides以 iso2 国家代码为键覆盖任意国家的显示名称const iti intlTelInput(input, { countryNameLocale: fr, countryNameOverrides: { us: États-Unis, }, });底层实现名称解析的优先级从源码看国家名称的生成逻辑集中在 country-data.ts 的generateCountryNames中对每个国家按以下优先级取第一个非空值countryNameOverrides中显式指定的名称uiTranslations中随语言包附带的内嵌国家名称countryNamesnew Intl.DisplayNames(countryNameLocale, { type: region })的查询结果空字符串兜底当浏览器不支持Intl.DisplayNames或传入非法 locale 时displayNames会被置为null。因此countryNameOverrides拥有最高优先级可以在任何场景下强制修正特定国家的显示文案。浏览器兼容性注意事项部分浏览器附带的是精简版Intl.DisplayNames数据会缺失某些 locale 的区域名称从而静默回退到英文。最典型的例子是Chrome 桌面版对以下 9 个语言缺失区域数据iso2语言az阿塞拜疆语bs波斯尼亚语ga爱尔兰语hy亚美尼亚语is冰岛语mk马其顿语mt马耳他语sq阿尔巴尼亚语uz乌兹别克语你不需要自己处理这个兼容性问题对于这些语言项目已将翻译好的国家名称内嵌进各自的intl-tel-input/locale模块中。仓库的 country-names 目录下恰好包含az.ts、bs.ts、ga.ts、hy.ts、is.ts、mk.ts、mt.ts、sq.ts、uz.ts这 9 个文件与上述列表一一对应。例如 az.ts 的默认导出是export default { ...interfaceTranslations, countryNames };也就是说只要把它作为uiTranslations传入就能在任何浏览器中获得正确的阿塞拜疆语国家名称。注意使用这类语言包作为uiTranslations时单独的countryNameLocale选项值会被忽略因为内嵌countryNames的优先级高于Intl.DisplayNames但你仍然可以用countryNameOverrides覆盖它们。本地化用户界面字符串使用uiTranslations选项可以翻译全部界面字符串包括国家搜索框占位符、无结果提示以及各种无障碍aria标签。从 locale 入口点导入翻译项目在intl-tel-input/locale这个入口点提供了大量语言翻译按需导入并传入uiTranslations即可。语言包的导出全部在自动生成的 locale/index.ts 中声明例如import { fr } from intl-tel-input/locale; const iti intlTelInput(input, { uiTranslations: fr, });覆盖单个翻译键如果你只需要修正其中一条文案可以用展开语法合并传入uiTranslationsimport { fr } from intl-tel-input/locale; const iti intlTelInput(input, { uiTranslations: { ...fr, // 覆盖国家搜索框占位符 searchPlaceholder: Rechercher, }, });这一用法之所以可行是因为在 options.ts 的applyOptionSideEffects中默认英文文案会与你的uiTranslations做浅合并o.uiTranslations { ...defaultEnglishStrings, ...o.uiTranslations };未提供的键自动回退到英文默认值因此你可以放心地只覆盖部分键。目前已支持的语言仓库目前为下列 57 个语言环境提供了 UI 翻译数量与 locale/index.ts 的导出列表一致ar、az、bg、bn、bs、ca、cs、da、de、el、en、es、et、fa、fi、fil、fr、ga、he、hi、hr、hu、hy、id、is、it、ja、kn、ko、lt、lv、mk、mr、ms、mt、nl、no、pl、pt、ro、ru、sk、sl、sq、sr、sv、sw、ta、te、th、tr、uk、ur、uz、vi、zh、zhHkzh-HK。没有你需要的语言你可以自行贡献一个新的翻译文件添加一个packages/core/src/js/locale/locale.ts模块并在 locale/index.ts 中导出也可以直接在初始化时传入自定义对象。集成测试 locale-bundles.test.js 会校验每个语言包必须包含全部必需键、且只能带countryNames这一个可选键确保新贡献的翻译不会漏掉界面文案。完整的可翻译键清单uiTranslations接受的全部键同时是语言包的必需键以默认英文值为参考见 en.ts{ // 已选择国家时所选国家元素的 aria 标签${countryName} 与 ${dialCode} 为运行时占位符 selectedCountryAriaLabel: Change country for phone number, currently selected ${countryName} (${dialCode}), // 未选择国家时所选国家元素的 aria 标签与标题文本 noCountrySelected: Select country for phone number, // 国家列表元素的 aria 标签 countryListAriaLabel: List of countries, // 国家搜索输入框的占位符 searchPlaceholder: Search, // 清除搜索按钮的 aria 标签 clearSearchAriaLabel: Clear search, // 全屏弹层关闭按钮的 aria 标签 closeCountrySelectorAriaLabel: Close, // 搜索无结果时的可见文本 searchEmptyState: No results found, // 搜索结果的读屏摘要函数形式接收结果数量 searchSummaryAria(count) { if (count 0) return No results found; if (count 1) return 1 result found; return ${count} results found; }, }这些键的类型定义在 locale/types.ts 的UiTranslations中。值得注意的是searchSummaryAria是一个函数语言包需要根据count处理单数、复数的语法差异——例如法语 fr.ts 中就是按 0、1、n 三档返回不同文案。countryNames按 iso2 键控的国家名称对象是可选键仅在上述 9 个受浏览器兼容性影响的语言包中出现。从右到左RTL布局在dirrtl的站点上html元素或其任意祖先设置了该属性组件布局会自动切换为从右到左流动无需额外配置。底层检测逻辑在 ui.ts 中this.#isRTL !!this.telInputEl.closest([dirrtl]);即通过closest沿 DOM 向上查找最近的dirrtl祖先来判定 RTL 环境。不过电话号码与区号仍然保持从左到右显示因为这是书写电话号码的标准方式。为此源码会在页面为 RTL 时给包裹元素设置dirltr见 ui.ts 附近的实现注释同时让独立区号separateDialCode显示在左侧并把国家选择器内部设置为 RTLui.tsthis.#countrySelectorEl.setAttribute(dir, rtl);这样外层国家选择器按 RTL 排布内层电话号码区域仍按 LTR 排布兼顾两种书写习惯。你可以在 Right to left 示例 中看到阿拉伯语场景的完整配置它同时设置了uiTranslations: ar、countryNameLocale: ar并将初始国家设为ps。替代数字Alternative Numeralsintl-tel-input支持使用非 ASCII 数字输入电话号码目前包括两套替代数字阿拉伯-印度数字Arabic-Indic٠ ١ ٢ ٣ ٤ ٥ ٦ ٧ ٨ ٩波斯 / 扩展阿拉伯-印度数字Persian / Extended Arabic-Indic۰ ۱ ۲ ۳ ۴ ۵ ۶ ۷ ۸ ۹这些数字在内部会被归一化为 ASCII0-9用于解析和校验isValidNumber、isValidNumberPrecise、getNumber等方法均正常工作而当输入值被更新时组件会保留用户原有的数字字集把结果镜像回对应的替代数字。底层实现Numerals 类归一化与反归一化由 numerals.ts 中的Numerals类实现核心逻辑为normalise(str)将阿拉伯-印度数字U0660–U0669和波斯数字U06F0–U06F9转换为 ASCII0-9同时以副作用方式记录用户使用的数字字集denormalise(str)把 ASCII0-9反向转换回用户字集尚未识别字集时原样返回static toAscii(str)无状态地执行数字转换不改变任何实例的追踪状态例如用于国家搜索查询串。public normalise(str: string): string { this.#updateNumeralSet(str); if (this.#userNumeralSet ascii) { return str; // 常见情况纯 ASCII 输入走快速路径跳过两次 replace } return Numerals.toAscii(str); }格式化的限制[!NOTE] 当用户输入非 ASCII 数字时输入即格式化format-as-you-type会被自动禁用因为在 RTL 数字字集下光标位置caret的追踪不可靠。这条行为同样被集成测试覆盖easternNumerals.test.js 验证了用阿拉伯-印度数字输入٤٤٧٩٤٧١٢٣٤٥٦时国旗正确切换到gb但输入过程中不做格式化该测试同时覆盖波斯数字、setNumber传入替代数字、替代数字下的strictMode、getNumber保留字集等场景。相关的单元测试见 numerals.test.js。综合示例接入一套完整的本地化配置把四个维度组合起来一个面向阿拉伯语用户的完整初始化配置如下参照 Right to left 示例import intlTelInput from intl-tel-input; import ar from intl-tel-input/locale/ar.js; // 阿拉伯语 const input document.querySelector(#phone); const iti intlTelInput(input, { uiTranslations: ar, // 界面文案使用阿拉伯语 countryNameLocale: ar, // 国家名称使用阿拉伯语被语言包内嵌 countryNames 覆盖优先级更高时自动生效 initialCountry: ps, loadUtils: () import(intl-tel-input/js/utils.js), });若站点html设置了dirrtl布局会自动调整为 RTL用户若输入波斯数字۰ ۱ ۲ ...组件会透明地完成解析校验并保留原字集回显。如果个别国家的名称或某条 UI 文案需要修正再通过countryNameOverrides或展开合并uiTranslations覆盖即可。小结国家名称countryNameLocale指定语言默认encountryNameOverrides最高优先级覆盖个别名称9 个受浏览器精简数据影响的语言包内嵌了国家名称无需自行处理兼容性。UI 文案uiTranslations支持从intl-tel-input/locale导入 57 种语言或传入自定义对象覆盖任意键默认英文文案会自动合并补齐。RTL 布局检测dirrtl祖先自动生效电话号码保持 LTR国家选择器单独 RTL。替代数字阿拉伯-印度与波斯数字输入自动归一化为 ASCII输入即格式化在非 ASCII 数字下自动关闭。上述全部选项的完整参数说明、默认值与取值约束可继续查阅 options.md 中对应的选项章节核心实现集中在 country-data.ts、ui.ts 与 numerals.ts测试佐证见 locale-bundles.test.js 与 easternNumerals.test.js。赞分享前端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数据缓存方案优化国家代码加载intl tel input数据缓存方案优化国家代码加载 在全球化应用开发中处理国际电话号码输入是常见需求。intl tel input作为一款成熟的Jav前端UI组件Groq Code CLI自定义教程3步添加专属Slash命令提升开发效率Groq Code CLI自定义教程3步添加专属Slash命令提升开发效率 Groq Code CLI是一款高度可定制、轻量级且开源的编码命令行工具由Groreact-native-orientation-locker 高级用法事件监听、方向锁定策略与性能优化react native orientation locker 高级用法事件监听、方向锁定策略与性能优化 react native orientation l上一篇Swift函数式编程DeskPad中的不可变状态与纯函数下一篇GameHub多语言支持国际化配置和本地化开发的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考