(isValid = v)} />
{#if isValid}
✓ Valid phone number
{/if}
```
### 可编译模式
关于自定义输入执行:
```svelte
Formatted: {phoneMask.fullFormatted}
Valid: {phoneMask.isComplete ? 'Yes' : 'No'}
Country: {phoneMask.country.name}
```
### 附件模式
用于现有 `` 没有折叠组件的元素。 需要斯维尔特5.29+.
```svelte
```
短手( 国家代码字符串 ):
```svelte
```
自动检测:
```svelte
```
### 行动模式
用于现有 `` 没有折叠组件的元素。 与 **所有 Svelte 5 版本** (包括5.29前). 反应参数变化通过Svelte 应用 `use:` 动作 `update()` 寿命轮钩.
```svelte
```
短手( 国家代码字符串 ):
```svelte
```
自动检测:
```svelte
```
### 发送 Raw 数字到后端
```svelte
```
### 关于国家变化的动态遮罩更新
```svelte
{phoneMask.fullFormatted}
{phoneMask.isComplete ? 'complete' : 'incomplete'}
```
### 多租户:租户Id 默认国家+特定租户审定规则
```svelte
Default country: {policy.defaultCountry}
Tenant validation: {isTenantValid ? 'pass' : 'fail'}
```
## ++ 显示格式
打电话 `formatPhone(value, country?, options?)` 直接在模板中。 它返回文本, 不需要 CSS .
```svelte
{formatPhone(phone, 'US', { code: false, flag: true })}
```
奥米 `country` 以检测一个完整的国际编号 `+`; 传递给没有调用代码的号码, 或解析美国/CA等共享调用代码. 可选 `PhoneFormatOptions` 参数接受 `code` (默认) `true`和 `flag` (默认) `false`) (中文(简体) ).
该功能在SSF期间有效. 不支持的值保持不变; 空白, 仅空白, `null`,以及 `undefined` 值返回空文本。 见 [格式规则](https://github.com/DeSource-Labs/phone-mask/blob/main/packages/core/README.md#formatphonevalue-country-options) 用于检测限度和实例.
## \* 构件 API
### 道具
> **说明:** 该组件支持控制模式和可约束模式。 使用 `bind:value` 用于双向绑定或 `value` + 键 `onchange` 用于控制模式.
```ts
interface PhoneInputProps {
// Bindable value (digits only, without country code)
value?: string;
// Optional id/name applied to the underlying for forms/autofill
id?: string;
name?: string;
// Preselected country (ISO 3166-1 alpha-2)
country?: CountryKey;
// Auto-detect country from IP/locale
detect?: boolean; // Default: true
// Locale for country names
locale?: string; // Default: browser language
// Size variant
size?: 'compact' | 'normal' | 'large'; // Default: 'normal'
// Visual theme ("auto" | "light" | "dark")
theme?: 'auto' | 'light' | 'dark'; // Default: 'auto'
// Disabled state
disabled?: boolean; // Default: false
// Readonly state
readonly?: boolean; // Default: false
// Show copy button
showCopy?: boolean; // Default: true
// Show clear button
showClear?: boolean; // Default: false
// Show validation state (borders & outline)
withValidity?: boolean; // Default: true
// Custom search placeholder
searchPlaceholder?: string; // Default: 'Search country or code...'
// Custom no results text
noResultsText?: string; // Default: 'No countries found'
// Custom clear button label
clearButtonLabel?: string; // Default: 'Clear phone number'
// Dropdown menu custom CSS class
dropdownClass?: string;
// Disable default styles
disableDefaultStyles?: boolean; // Default: false
// Extra CSS class merged onto root element
class?: string;
// Callback when the phone number changes.
// Provides an object with:
// - full: Full phone number with country code (e.g. +1234567890)
// - fullFormatted: Full phone number formatted according to country rules (e.g. +1 234-567-890)
// - digits: Only the digits of the phone number without country code (e.g. 234567890)
onchange?: (value: PhoneNumber) => void;
// Callback when the selected country changes
oncountrychange?: (country: MaskFull) => void;
// Callback when the validation state changes
onvalidationchange?: (isValid: boolean) => void;
// Callback when the input is focused
onfocus?: (event: FocusEvent) => void;
// Callback when the input is blurred
onblur?: (event: FocusEvent) => void;
// Callback when phone number is copied
oncopy?: (value: string) => void;
// Callback when input is cleared
onclear?: () => void;
}
```
### 被曝光的方法
通过 `bind:this`数字 :
```svelte
```
```ts
interface PhoneInputExposed {
focus: () => void; // Focus the input
blur: () => void; // Blur the input
clear: () => void; // Clear the input value
selectCountry: (code: string) => void; // Programmatically select a country by ISO code
getFullNumber: () => string; // Returns full phone number with country code (e.g. +1234567890)
getFullFormattedNumber: () => string; // Returns formatted number with country code (e.g. +1 234-567-890)
getDigits: () => string; // Returns only digits without country code (e.g. 234567890)
isValid: () => boolean; // Checks if the current phone number is valid
isComplete: () => boolean; // Alias for isValid()
}
```
### 片断
```svelte
{#snippet flag(country)}
}.svg)
{/snippet}
{#snippet copysvg(copied)}
{copied ? '✓' : '📋'}
{/snippet}
{#snippet clearsvg()}
✕
{/snippet}
{#snippet actionsbefore()}
{/snippet}
```
| 片断 | 道具 | 说明 |
| --- | --- | --- |
| `flag` | `MaskFull` | 自定义国家列表和选择器中的旗帜图标 |
| `copysvg` | `boolean` (复制状态) | 自定义复制按钮图标 |
| `clearsvg` | —— 说 | 自定义清除按钮图标 |
| `actionsbefore` | —— 说 | 默认动作按钮前的内容 |
## ++可编译的 API
### 选项
> **说明:** 可混凝土功能用于反应性选项. 不要直接传递值.
```ts
interface UsePhoneMaskOptions {
// Getter returning current digit value (controlled) - REQUIRED
value: () => string;
// Callback when the digits value changes - REQUIRED
onChange: (digits: string) => void;
// Getter for ISO country code (e.g., 'US', 'DE', 'GB')
country?: () => string | undefined;
// Getter for locale string (default: navigator.language)
locale?: () => string | undefined;
// Getter for auto-detect flag (default: false)
detect?: () => boolean | undefined;
// Callback when the phone changes (full, fullFormatted, digits)
onPhoneChange?: (phone: PhoneNumber) => void;
// Country change callback
onCountryChange?: (country: MaskFull) => void;
}
```
### 返回值
> **重要内容:** 不要对返回对象进行分解——所有属性都是被动取出器和分解断裂反应.
```ts
interface UsePhoneMaskReturn {
// Ref to attach to your input element
inputRef: HTMLInputElement | null;
// Raw digits without formatting (e.g., "1234567890")
digits: string;
// Phone formatter instance
formatter: FormatterHelpers;
// Full phone number with country code (e.g., "+11234567890")
full: string;
// Full phone number formatted (e.g., "+1 123-456-7890")
fullFormatted: string;
// Whether the phone number is complete
isComplete: boolean;
// Whether the input is empty
isEmpty: boolean;
// Whether to show validation warning
shouldShowWarn: boolean;
// Current country data
country: MaskFull;
// Current locale used for country names
locale: string;
// Change country programmatically
setCountry: (countryCode?: string | null) => boolean;
// Clear the input
clear: () => void;
}
```
```svelte
```
## 附录 API
这个 `phoneMaskAttachment` Svelte附件(Svelte 5.29+)直接适用于任何 `` 元素通过 `{@attach phoneMaskAttachment(...)}`不同 `use:` 当呼叫站点中的反应状态发生变化时,附件厂会重新进行反应运行——没有手动操作 `update()` 需要帮助.
### 基本用途
```svelte
```
### 选项
```ts
import type { PMaskFull, PMaskPhoneNumber } from '@desource/phone-mask-svelte';
interface PhoneMaskBindingOptions {
// Predefined country ISO code (e.g., 'US', 'DE', 'GB')
country?: string;
// Locale for country names (default: navigator.language)
locale?: string;
// Auto-detect country from IP/locale (default: false)
detect?: boolean;
// Value change callback
onChange?: (phone: PMaskPhoneNumber) => void;
// Country change callback
onCountryChange?: (country: PMaskFull) => void;
}
```
参数可以是国家代码字符串(shorthand)或选项对象:
```svelte
```
### 反应国
直接通过反应状态——工厂在 `selectedCountry` 变化 :
```svelte
(phoneData = p) })} placeholder="Phone number" />
```
## 行动 API
这个 `phoneMaskAction` Svelte动作将手机口罩直接应用到任何 `` 元素通过 `use:phoneMaskAction`它与 **所有 Svelte 5 版本** ——不需要斯维尔特5.29+.
当绑定参数对象发生变化时(例如一个新的) `country` 值, Svelte 自动调用动作的 `update()` 钩子,可以重新应用新的选项,必要时可以切换国家.
### 基本用途
```svelte
```
### 选项
```ts
import type { PMaskFull, PMaskPhoneNumber } from '@desource/phone-mask-svelte';
interface PhoneMaskBindingOptions {
// Predefined country ISO code (e.g., 'US', 'DE', 'GB')
country?: string;
// Locale for country names (default: navigator.language)
locale?: string;
// Auto-detect country from GeoIP on mount; falls back to locale detection
detect?: boolean;
// Value change callback — fires on every phone number change
onChange?: (phone: PMaskPhoneNumber) => void;
// Country change callback — fires on initial mount and on country switch
onCountryChange?: (country: PMaskFull) => void;
}
```
参数可以是国家代码字符串(shorthand)或选项对象:
```svelte
```
### 反应国
被动通过 `$state` 在选项对象内——斯维尔特调用 `update()` 当 `selectedCountry` 变化 :
```svelte
(phoneData = p) }} placeholder="Phone number" />
```
### 动作对附件
| | `use:phoneMaskAction` | `{@attach phoneMaskAttachment(...)}` |
| --- | --- | --- |
| 需要斯维尔特版本 | 全斯维尔特5 | 丝绒 5.29+ |
| 反应机制 | `update()` 钩(自发) | 工厂进行反应式再运行 |
| 手动 `update()` 需求 | 不(Svelte处理它) | 没有 |
## 组件样式
### CSS 自定义属性
通过 CSS 变量自定义颜色 :
```css
.desource-phone-input,
.desource-phone-dropdown {
/* Colors */
--pi-bg: #ffffff;
--pi-fg: #111827;
--pi-muted: #6b7280;
--pi-border: #e5e7eb;
--pi-border-hover: #d1d5db;
--pi-border-focus: #3b82f6;
--pi-focus-ring: 3px solid rgb(59 130 246 / 0.15);
--pi-disabled-bg: #f9fafb;
--pi-disabled-fg: #9ca3af;
/* Sizes */
--pi-font-size: 16px;
--pi-height: 44px;
/* Spacing */
--pi-padding: 12px;
/* Border radius */
--pi-radius: 8px;
/* Shadows */
--pi-shadow: 0 1px 2px 0 rgb(0 0 0 / 0.05);
--pi-shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -2px rgb(0 0 0 / 0.05);
/* Validation */
--pi-warning: #f59e0b;
--pi-warning-light: #fbbf24;
--pi-success: #10b981;
--pi-focus-ring-warning: 3px solid rgb(245 158 11 / 0.15);
--pi-focus-ring-success: 3px solid rgb(16 185 129 / 0.15);
}
```
### 黑暗主题
```svelte
```
或与CSS: (中文(简体) )
```css
.desource-phone-input.theme-dark {
--pi-bg: #1f2937;
--pi-fg: #f9fafb;
--pi-border: #374151;
}
```
## 实例
### 有验证
```svelte
(isValid = v)} />
{#if errorMessage}
{errorMessage}
{/if}
```
### 自动检测国家
```svelte
{#if detectedCountry}
Detected: {detectedCountry}
{/if}
```
### 程序控制
```svelte
Full: {phoneInput?.getFullFormattedNumber()}
Valid: {phoneInput?.isValid()}
```
### 多个输入
```svelte
```
### 自定义可编译执行
```svelte
Formatted: {phoneMask.fullFormatted}
Valid: {phoneMask.isComplete ? 'Yes' : 'No'}
Country: {phoneMask.country.name}
```
## QQ 浏览器支持
- 克罗梅/第90号+
- Firefox 88+ (英语)
- 萨法里14+
- iOS 萨法里14+
- Chrome 移动
## 包含什么
```
@desource/phone-mask-svelte/
├── dist/
│ ├── index.js # Main Svelte package entry
│ ├── index.d.ts # Root TypeScript declarations
│ ├── components/
│ │ └── PhoneInput.svelte # Consumer-compiled Svelte component
│ ├── core.js # Core kit utilities and mask data subpath
│ ├── core.d.ts # Core subpath declarations
│ ├── phone-mask-svelte.css # Component styles
│ └── ... # Supporting modules and colocated declarations
├── README.md # This file
└── package.json # Package manifest
```
包运本地的 Svelte 组件和 rune 模块, 因此您的 Svelte 构建为浏览器或服务器 。 它需要Svelte-aware工具;没有预编集的CommonJS组件条目.
## 有关软件包
- [@ desource/ phone- mask (英语)](https://github.com/DeSource-Labs/phone-mask/blob/main/packages/core) - 核心图书馆
- [@ desource/ phone- mask- angular (英语)](https://github.com/DeSource-Labs/phone-mask/blob/main/packages/angular) - 角装订
- [@ desource/ phone- mask- react](https://github.com/DeSource-Labs/phone-mask/blob/main/packages/react) - 反应约束
- [@ 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-svelte 是什么？
🌍 Svelte 5 组件,可编程,动作和附件用于国际电话号码口罩\. 由@desource/ phone- mask提供, 并同步 Google libphone 数字\.
### 如何安装 @desource/phone-mask-svelte？
在项目目录运行 npm install @desource/phone-mask-svelte，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：svelte（^5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。
### @desource/phone-mask-svelte 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @desource/phone-mask-svelte 支持 ESM 还是 CommonJS？
以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。
### @desource/phone-mask-svelte 可以商用吗？
@desource/phone-mask-svelte 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @desource/phone-mask-svelte 的下载量有多少？
根据 npm 官方下载统计，@desource/phone-mask-svelte 在 2026/10/12 – 2026/11/10 这 30 天内被下载 19,699 次，日均约 657 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @desource/phone-mask-svelte 还在维护吗？
最新版本 2\.1\.0 发布于 2026/11/07（4 天前）；至今共发布 18 个版本，其中过去 12 个月发布了 18 个；首次发布于 2026/03/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。