# @desource/phone-mask-angular 中文文档
规范地址：https://npmcn.com/package/%40desource/phone-mask-angular/
版本：2\.1\.0
npm 元数据更新时间：2026-11-07T02:46:23.897Z
中文译文更新时间：2026-11-12T01:42:43.233Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40desource/phone-mask-angular
原文对照：https://npmcn.com/package/%40desource/phone-mask-angular/?lang=original
项目主页：https://github.com/DeSource-Labs/phone-mask/tree/main/packages/angular#readme
源码仓库：https://github.com/DeSource-Labs/phone-mask
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：179 kB，11 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：@angular/core ^19\.0\.0 \|\| ^20\.0\.0 \|\| ^21\.0\.0 \|\| ^22\.0\.0，@angular/forms ^19\.0\.0 \|\| ^20\.0\.0 \|\| ^21\.0\.0 \|\| ^22\.0\.0，@angular/common ^19\.0\.0 \|\| ^20\.0\.0 \|\| ^21\.0\.0 \|\| ^22\.0\.0
- 首次发布：2026-10-31T14:42:27.178Z
- 最新版本发布：2026-11-07T02:46:23.532Z
- 近 30 天下载量：10223（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）
## 中文简介
以信号为主的Angular电话输入,指令和格式化管得到SSR支持.
## 安装
```sh
npm install @desource/phone-mask-angular
```
也可以使用：`pnpm add @desource/phone-mask-angular`、`yarn add @desource/phone-mask-angular`、`bun add @desource/phone-mask-angular`
## README
# @ desource/ phone- mask- angular (英语)
> 角电话输入组件,无头口罩功能,指令,以及带有Google libphone数字数据的管子
[](https://www.npmjs.com/package/@desource/phone-mask-angular) [](https://codecov.io/gh/DeSource-Labs/phone-mask) [](https://sonarcloud.io/summary/new_code?id=DeSource-Labs_phone-mask) [](https://codewiki.google/github.com/desource-labs/phone-mask) [](https://context7.com/desource-labs/phone-mask) [](https://deepwiki.com/DeSource-Labs/phone-mask) [](https://github.com/DeSource-Labs/phone-mask/blob/main/LICENSE)
为Angular 19–22提供独立,以信号为主的电话输入,由共享手机-掩码核心提供动力.
## \* 特性
- 具有信号输入、双向绑定的独立组件,以及 `OnPush` 变化检测.
- SSR和水合支持,包括格式化的服务器HTML.
- 无分区操作: 库不导入或需要 `zone.js`。 。 。 .
- 通过反应和模板驱动的角形式 `ControlValueAccessor`。 。 。 .
- 国家搜索,键盘导航,智能光标处理,并粘贴格式化.
- 浅/暗主题,复制和清晰的行动,以及验证反馈.
- 可选地理IP探测和本地化国名.
- 由 CSS 和 树形可摇动的 Angular 软件包格式构建 `ng-packagr`。 。 。 .
## \* 安装
```bash
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` 在应用程序中的匹配版本.
在全局样式表中导入组件样式一次 :
```css
@import '@desource/phone-mask-angular/assets/lib.css';
```
指令,无头面具功能,和管子不需要这些样式.
## QQ 快速启动
### 导入
```ts
import { PhoneInputComponent, PhoneMaskDirective, PhonePipe, usePhoneMask } from '@desource/phone-mask-angular';
```
在您的独立组件中添加组件、 指令或管道 `imports`调用 `usePhoneMask()` 在构建自定义输入时的注入上下文.
### 组件模式
```ts
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { PhoneInputComponent } from '@desource/phone-mask-angular';
@Component({
selector: 'app-profile',
imports: [PhoneInputComponent],
changeDetection: ChangeDetectionStrategy.OnPush,
template: `
Digits without calling code: {{ phone() }}
`
})
export class Profile {
readonly phone = signal('2025550123');
}
```
`value` 包含数字,没有国家呼叫代码。 使用 `phoneChange` 国际编号:
```html
```
粘贴完整的国际编号,首先是 `+` 从现有的口罩中检测其国家,替换全部输入,在格式化前更新国家. 这适用于组件、指令和 `usePhoneMask()`,即使与 `country` 提供或地理IP `detect` 已禁用。 隐蔽口罩使用默认国家,例如美国 `+1`。其他粘贴保持当前国家并使用正常的插入行为.
## \* 构件 API
### 投入
| 投入 | 类型 | 默认 |
| --- | --- | --- |
| `value` | `string` | `''` |
| `country` | ISO 国家代码 | 未指定;有国家选择 |
| `detect` | `boolean` | `true` |
| `locale` | `string` | 服务器上的英语, 渲染后的浏览器语言 |
| `theme` | `'auto' | 'light' | 'dark'` | `'auto'` |
| `size` | `'compact' | 'normal' | 'large'` | `'normal'` |
| `id`, (中文(简体) ), `name` | `string` | 未指定; 适用于本地输入 |
| `disabled`, (中文(简体) ), `readonly` | `boolean` | `false` |
| `showCopy` | `boolean` | `true` |
| `showClear` | `boolean` | `false` |
| `withValidity` | `boolean` | `true` |
| `searchPlaceholder` | `string` | `'Search country or code...'` |
| `noResultsText` | `string` | `'No countries found'` |
| `clearButtonLabel` | `string` | `'Clear phone number'` |
| `dropdownClass` | `string` | `''` |
| `disableDefaultStyles` | `boolean` | `false` |
设置 `country` 锁定国家选择器。 允许用户选择一个国家; 使用 `selectCountry()` 设置初始选择而不锁定它.
### 产出
| 产出 | 数值 |
| --- | --- |
| `valueChange` | 数字没有调用代码,用于 `[(value)]` |
| `phoneChange` | `{ digits, full, fullFormatted }` |
| `countryChange` | 国家元数据(`PMaskFull`(中文(简体) ) |
| `validationChange` | 是否所有所需的数字都存在 |
| `phoneFocus`, (中文(简体) ), `phoneBlur` | 土著 `FocusEvent` |
| `touchedChange` | `true` 模糊,用于信号窗体相容性 |
| `copied` | 复制电话号码 |
| `cleared` | 无有效载荷 |
### 被曝光的方法
通过角模板参考或 `viewChild`数字 :
```html
```
还提供: `blur()`, (中文(简体) ), `getDigits()`, (中文(简体) ), `getFullNumber()`, (中文(简体) ), `getFullFormattedNumber()`, (中文(简体) ), `isComplete()`,以及 `isValid()`。完整性检查数字与所选的口罩进行计数;它不核实一个数字是否被指定或可到达.
### 自定义模板
通过角 `TemplateRef` 结束 `flagTemplate`, (中文(简体) ), `copyTemplate`, (中文(简体) ), `clearTemplate`,或 `actionsTemplate`。旗帜模板接收国家为 `$implicit` 财务报告和审定财务报表 `country`; 复制模板接收复制状态为 `$implicit` 财务报告和审定财务报表 `copied`。 。 。 .
```html
{{ country.id }}
```
`actionsTemplate` 并保留一个动作的宽度。 覆盖 `--pi-actions-count` 如果您的模板需要更多的空间.
## 角形式
导入 `ReactiveFormsModule` 与组件并列:
```ts
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: ``
})
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`数字 :
```html
```
对于一个固定的国家来说, `phoneMask="US"` 等同的。 该指令与Angular Form集成,并通过其值存取器发出没有调用代码的位数. 它的选择接受 `country`, (中文(简体) ), `locale`, (中文(简体) ), `detect`, (中文(简体) ), `onChange`,以及 `onCountryChange`。检测默认值为 `false` 对指令.
```html
```
`onChange` 接收 `{ digits, full, fullFormatted }`· ; `onCountryChange` 接收国家元数据.
## 无头 API
`usePhoneMask()` 是无头遮罩功能,用于自定义输入时会暴露一个基于信号的API. 在Angular注射上下文中称它,如组件域初始化. 国家和清理属于这一组成部分.
```ts
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: `
{{ mask.fullFormatted() }}
`
})
export class CustomPhone {
readonly input = viewChild>('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国家代码或解决共享调用代码的国家:
```html
{{ '+12345678888' | phone }}
{{ '+12345678888' | phone: 'US': { code: false } }}
{{ '+12345678888' | phone: 'US': { flag: true } }}
{{ '+12345678888' | phone: 'US': { code: false, flag: true } }}
```
数字没有调用代码( N)`'2345678888'`)和预格式值(`'234 567 8888'` 或者说 `'+1 234 567 8888'`)输出相同. 管子使用所选国家的口罩组,由空格分隔.
可选第二个参数接受导出 `PhonePipeOptions` 类型 :
| 选项 | 类型 | 默认 | 效果 |
| --- | --- | --- | --- |
| `code` | `boolean` | `true` | 包括国家呼叫代码. |
| `flag` | `boolean` | `false` | 预置国旗emoji. |
只有一个明确 `+` 调用代码从输入中被去除; 光数字作为数字处理,没有调用代码. 没有国家,没有呼叫代码和检测失败的数字返回原值。 遮罩检测使用默认的联系国, 如美国 `+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()` 在有资源的情况下。 见 [角形无带向导](https://angular.dev/guide/zoneless) 财务报告和审定财务报表 [水分指导](https://angular.dev/guide/hydration)。 。 。 .
## 组件样式
样式选择通过 `assets/lib.css`设置 CSS 自定义属性 `.desource-phone-input` 财务报告和审定财务报表 `.desource-phone-dropdown`数字 :
```css
.desource-phone-input,
.desource-phone-dropdown {
--pi-radius: 6px;
--pi-border-focus: #2563eb;
--pi-font-size: 16px;
}
```
滴滴是附着在 `document.body` 避免被母容器剪接。 在全球应用下拉覆盖或使用 `dropdownClass`;组件范围CSS无法到达门户.
## \* 核心公用事业
二级入境点再出口共享的核心公用事业和国家数据:
```ts
import { getFlagEmoji, formatDigitsWithMap } from '@desource/phone-mask-angular/core';
```
## 包含什么
已出版的软件包包含了未识别的FE SM2022模块,部分Angular声明,TypeScript声明,以及单独的CSS. Angular的应用程序构建了链接并优化了库. 需要无害环境管理和Angular的链接器;没有提供UMD或CommonJS的构建.
```text
@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 (英语)](https://github.com/DeSource-Labs/phone-mask/blob/main/packages/core) - 核心图书馆
- [@ desource/ phone- mask- react](https://github.com/DeSource-Labs/phone-mask/blob/main/packages/react) - 反应约束
- [@ desource/ phone- massk- svelte (英语)](https://github.com/DeSource-Labs/phone-mask/blob/main/packages/svelte) - 丝绒装订
- [@ desource/ phone- mask- vue](https://github.com/DeSource-Labs/phone-mask/blob/main/packages/vue) - Vue 3装订
- [@ desource/ phone- mask- nuxt](https://github.com/DeSource-Labs/phone-mask/blob/main/packages/nuxt) - 努克特模块
## 许可证
[麻省理工学院](https://github.com/DeSource-Labs/phone-mask/blob/main/LICENSE) 2026 来源实验室
## 捐款
见 [贡献指南](https://github.com/DeSource-Labs/phone-mask/blob/main/CONTRIBUTING.md) 用于开发、测试和出版检查.
* * *
由 Q 制作 [来源实验室](https://github.com/DeSource-Labs)
## 常见问题
### @desource/phone-mask-angular 是什么？
以信号为主的Angular电话输入,指令和格式化管得到SSR支持\.
### 如何安装 @desource/phone-mask-angular？
在项目目录运行 npm install @desource/phone-mask-angular，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@angular/core（^19\.0\.0 \|\| ^20\.0\.0 \|\| ^21\.0\.0 \|\| ^22\.0\.0）、@angular/forms（^19\.0\.0 \|\| ^20\.0\.0 \|\| ^21\.0\.0 \|\| ^22\.0\.0）、@angular/common（^19\.0\.0 \|\| ^20\.0\.0 \|\| ^21\.0\.0 \|\| ^22\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。
### @desource/phone-mask-angular 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @desource/phone-mask-angular 支持 ESM 还是 CommonJS？
以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。
### @desource/phone-mask-angular 可以商用吗？
@desource/phone-mask-angular 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @desource/phone-mask-angular 的下载量有多少？
根据 npm 官方下载统计，@desource/phone-mask-angular 在 2026/10/12 – 2026/11/10 这 30 天内被下载 10,223 次，日均约 341 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @desource/phone-mask-angular 还在维护吗？
最新版本 2\.1\.0 发布于 2026/11/07（4 天前）；至今共发布 3 个版本，其中过去 12 个月发布了 3 个；首次发布于 2026/10/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。