@ desource/ phone- mask- angular (英语)

角电话输入组件,无头口罩功能,指令,以及带有Google libphone数字数据的管子

为Angular 19–22提供独立,以信号为主的电话输入,由共享手机-掩码核心提供动力.

* 特性

• 具有信号输入、双向绑定的独立组件,以及 OnPush 变化检测.
• SSR和水合支持,包括格式化的服务器HTML.
• 无分区操作: 库不导入或需要 zone.js。 。 。 .
• 通过反应和模板驱动的角形式 ControlValueAccessor。 。 。 .
• 国家搜索,键盘导航,智能光标处理,并粘贴格式化.
• 浅/暗主题,复制和清晰的行动,以及验证反馈.
• 可选地理IP探测和本地化国名.
• 由 CSS 和 树形可摇动的 Angular 软件包格式构建 ng-packagr。 。 。 .

* 安装

npm install @desource/phone-mask-angular
# or
yarn add @desource/phone-mask-angular
# or
pnpm add @desource/phone-mask-angular

该软件包支持Angular 19–22. 保留 @angular/common, (中文(简体) ), @angular/core,以及 @angular/forms 在应用程序中的匹配版本.

在全局样式表中导入组件样式一次 :

@import '@desource/phone-mask-angular/assets/lib.css';

指令,无头面具功能,和管子不需要这些样式.

QQ 快速启动

导入

import { PhoneInputComponent, PhoneMaskDirective, PhonePipe, usePhoneMask } from '@desource/phone-mask-angular';

在您的独立组件中添加组件、 指令或管道 imports调用 usePhoneMask() 在构建自定义输入时的注入上下文.

组件模式

import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { PhoneInputComponent } from '@desource/phone-mask-angular';

@Component({
  selector: 'app-profile',
  imports: [PhoneInputComponent],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <label for="mobile">Mobile number</label>
    <phone-input id="mobile" name="mobile" country="US" [(value)]="phone" />
    <p>Digits without calling code: {{ phone() }}</p>
  `
})
export class Profile {
  readonly phone = signal('2025550123');
}

value 包含数字,没有国家呼叫代码。 使用 phoneChange 国际编号:

<phone-input [(value)]="phone" (phoneChange)="savePhone($event.full)" />

粘贴完整的国际编号,首先是 + 从现有的口罩中检测其国家,替换全部输入,在格式化前更新国家. 这适用于组件、指令和 usePhoneMask(),即使与 country 提供或地理IP detect 已禁用。 隐蔽口罩使用默认国家,例如美国 +1。其他粘贴保持当前国家并使用正常的插入行为.

* 构件 API

投入

设置 country 锁定国家选择器。 允许用户选择一个国家; 使用 selectCountry() 设置初始选择而不锁定它.

产出

被曝光的方法

通过角模板参考或 viewChild数字 :

<phone-input #phoneInput [(value)]="phone" />
<button type="button" (click)="phoneInput.focus()">Focus</button>
<button type="button" (click)="phoneInput.selectCountry('GB')">Use UK</button>
<button type="button" (click)="phoneInput.clear()">Clear</button>

还提供: blur(), (中文(简体) ), getDigits(), (中文(简体) ), getFullNumber(), (中文(简体) ), getFullFormattedNumber(), (中文(简体) ), isComplete(),以及 isValid()。完整性检查数字与所选的口罩进行计数;它不核实一个数字是否被指定或可到达.

自定义模板

通过角 TemplateRef 结束 flagTemplate, (中文(简体) ), copyTemplate, (中文(简体) ), clearTemplate,或 actionsTemplate。旗帜模板接收国家为 $implicit 财务报告和审定财务报表 country; 复制模板接收复制状态为 $implicit 财务报告和审定财务报表 copied。 。 。 .

<ng-template #flag let-country>{{ country.id }}</ng-template>
<ng-template #actions><button class="pi-btn" type="button" (click)="openHelp()">Help</button></ng-template>
<phone-input [(value)]="phone" [flagTemplate]="flag" [actionsTemplate]="actions" />

actionsTemplate 并保留一个动作的宽度。 覆盖 --pi-actions-count 如果您的模板需要更多的空间.

角形式

导入 ReactiveFormsModule 与组件并列:

import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { PhoneInputComponent } from '@desource/phone-mask-angular';

@Component({
  selector: 'app-contact-form',
  imports: [ReactiveFormsModule, PhoneInputComponent],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `<phone-input country="US" [formControl]="phone" />`
})
export class ContactForm {
  readonly phone = new FormControl('', { nonNullable: true });
}

形式值包含数字,而不包含国家调用代码 。 该部分宣传变化、触摸状态和残疾状态。 将您的应用程序的验证符添加到控件中; 视觉完整性反馈不会注册表单验证符 .

对所选国家有效的供应数字,不包括呼叫码. 程序值被格式化并夹住以显示,而不重写格式模型; 使用 phoneChange 事件 digits 字段来观察峡谷值.

模板驱动的表格也与 FormsModule 财务报告和审定财务报表 [(ngModel)]。选择约束或 [(value)] 对于每个输入,所以一个所有者控制值.

信号形式也通过组件的现有装订来工作: 角 21.0 使用 Field 编号 : [field]; 角22 用途 FormField 编号 : [formField]。使用您安装的Angular 版本中可用的 API。 这个 touchedChange 输出为Angular 21的集成保留了模糊的处理.

指令 API

使用带有自己标记和样式的本地输入 。 导入 PhoneMaskDirective 输入组件 imports数字 :

<input [phoneMask]="{ country: 'US' }" [(ngModel)]="phone" />

对于一个固定的国家来说, phoneMask="US" 等同的。 该指令与Angular Form集成,并通过其值存取器发出没有调用代码的位数. 它的选择接受 country, (中文(简体) ), locale, (中文(简体) ), detect, (中文(简体) ), onChange,以及 onCountryChange。检测默认值为 false 对指令.

<input [phoneMask]="{ country: selectedCountry(), onChange: onPhoneChange }" />

onChange 接收 { digits, full, fullFormatted }· ; onCountryChange 接收国家元数据.

无头 API

usePhoneMask() 是无头遮罩功能,用于自定义输入时会暴露一个基于信号的API. 在Angular注射上下文中称它,如组件域初始化. 国家和清理属于这一组成部分.

import { ChangeDetectionStrategy, Component, ElementRef, signal, viewChild } from '@angular/core';
import { usePhoneMask } from '@desource/phone-mask-angular';

@Component({
  selector: 'app-custom-phone',
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <input
      #input
      type="tel"
      [value]="mask.displayValue()"
      [placeholder]="mask.displayPlaceholder()"
      aria-label="Phone number"
    />
    <p>{{ mask.fullFormatted() }}</p>
    <button type="button" (click)="mask.setCountry('GB')">Use UK</button>
  `
})
export class CustomPhone {
  readonly input = viewChild<ElementRef<HTMLInputElement>>('input');
  readonly digits = signal('');
  readonly mask = usePhoneMask({
    input: () => this.input()?.nativeElement,
    value: this.digits,
    onChange: (digits) => this.digits.set(digits),
    country: 'US'
  });
}

捆绑 displayValue 财务报告和审定财务报表 displayPlaceholder 在模板中提供自定义输入值。 该功能在浏览器渲染后附加了编辑行为,并在输入或组件被破坏时删除听众.

value 财务报告和审定财务报表 onChange 需要这样做。 通过一个 input 获取ter 将编辑行为附加到本地输入; 仅消耗格式化信号时可省略 。 选项 country, (中文(简体) ), locale,以及 detect 接受一个纯值、信号或更佳值。 检测默认值 false。可选回调为 onPhoneChange 财务报告和审定财务报表 onCountryChange。 。 。 .

返回值显示信号 digits, (中文(简体) ), displayValue, (中文(简体) ), displayPlaceholder, (中文(简体) ), full, (中文(简体) ), fullFormatted, (中文(简体) ), country, (中文(简体) ), locale, (中文(简体) ), formatter, (中文(简体) ), isComplete, (中文(简体) ), isEmpty,以及 shouldShowWarn,则 setCountry(code) 编号 : clear() 方法。 。 .

管道 API

导入 PhonePipe 输入您的组件 imports 显示电话号码。 首先是国际价值 + 可以从他们的面具和长度来检测国家。 通过一个没有调用代码的ISO国家代码或解决共享调用代码的国家:

{{ '+12345678888' | phone }}
<!-- +1 234 567 8888 -->
{{ '+12345678888' | phone: 'US': { code: false } }}
<!-- 234 567 8888 -->
{{ '+12345678888' | phone: 'US': { flag: true } }}
<!-- 🇺🇸 +1 234 567 8888 -->
{{ '+12345678888' | phone: 'US': { code: false, flag: true } }}
<!-- 🇺🇸 234 567 8888 -->

数字没有调用代码( N)'2345678888')和预格式值('234 567 8888' 或者说 '+1 234 567 8888')输出相同. 管子使用所选国家的口罩组,由空格分隔.

可选第二个参数接受导出 PhonePipeOptions 类型 :

只有一个明确 + 调用代码从输入中被去除; 光数字作为数字处理,没有调用代码. 没有国家,没有呼叫代码和检测失败的数字返回原值。 遮罩检测使用默认的联系国, 如美国 +1;它不检查区域编码分配。 过 undefined 或者说 null 作为将检测与选择相结合的国家.

被供应国在调用代码符合值时优先,所以 CA 保持加拿大国旗 +1如果调用代码不同,则成功检测优先: '+7 123 456 7788' | phone: 'US' 显示 +7 123 456 7788 使用 KZ。 如果检测失败, 则保留原始值 .

管子保留了显著的正0并不会推断出干线前缀或扩展. 空的,只有白空间, null,以及 undefined 数值变为 ''。不支持的国家、无效字符、扩展名和数字超过所选掩码长度,返回原始值不变.

该管是纯的,在SSR期间工作,没有浏览器API. 当值、 国家或选项引用改变时, 又是角格式 。 内置选项的工作如上所示;在改变其属性时替换被存储的选项对象.

SSR和无区应用程序

使用正常的Angular SSR和水分设置. 图书馆不需要 ngSkipHydration,只有浏览器的包装,或者Zone.js.

服务器渲染使用确定性默认值: 英语国家名称和当 theme="auto"。浏览器渲染后,组件会应用浏览器的用地和颜色偏好。 GeoIP请求只在浏览器中运行. 设定 country, (中文(简体) ), locale,并明确 theme 当服务器已经知道这些首选项时, 您想要相同的初始外观 .

角21+默认使用无区变化检测. 早期版本需要匹配的靴子陷阱提供者 : provideExperimentalZonelessChangeDetection() 在角19和早期角20,或 provideZonelessChangeDetection() 在有资源的情况下。 见 角形无带向导 财务报告和审定财务报表 水分指导。 。 。 .

组件样式

样式选择通过 assets/lib.css设置 CSS 自定义属性 .desource-phone-input 财务报告和审定财务报表 .desource-phone-dropdown数字 :

.desource-phone-input,
.desource-phone-dropdown {
  --pi-radius: 6px;
  --pi-border-focus: #2563eb;
  --pi-font-size: 16px;
}

滴滴是附着在 document.body 避免被母容器剪接。 在全球应用下拉覆盖或使用 dropdownClass;组件范围CSS无法到达门户.

* 核心公用事业

二级入境点再出口共享的核心公用事业和国家数据:

import { getFlagEmoji, formatDigitsWithMap } from '@desource/phone-mask-angular/core';

包含什么

已出版的软件包包含了未识别的FE SM2022模块,部分Angular声明,TypeScript声明,以及单独的CSS. Angular的应用程序构建了链接并优化了库. 需要无害环境管理和Angular的链接器;没有提供UMD或CommonJS的构建.

@desource/phone-mask-angular/
├── phone-mask-angular.css                     # Component styles, exported as assets/lib.css
├── core/index.d.ts                            # Core utilities and country data types
├── fesm2022/
│   ├── desource-phone-mask-angular.mjs         # Component, headless API, directive, and pipe
│   └── desource-phone-mask-angular-core.mjs    # Core secondary entry point
├── index.d.ts                                 # Public API declarations
├── README.md
└── package.json

有关软件包

• @ desource/ phone- mask (英语) - 核心图书馆
• @ desource/ phone- mask- react - 反应约束
• @ desource/ phone- massk- svelte (英语) - 丝绒装订
• @ desource/ phone- mask- vue - Vue 3装订
• @ desource/ phone- mask- nuxt - 努克特模块

许可证

麻省理工学院 2026 来源实验室

捐款

见 贡献指南 用于开发、测试和出版检查.