# @formio/text-mask-addons 中文文档

规范地址：https://npmcn.com/package/%40formio/text-mask-addons/

版本：3\.8\.0-formio\.4
npm 元数据更新时间：2025-05-23T15:43:50.353Z
中文译文更新时间：2026-11-15T09:03:23.923Z
软件包许可：Unlicense

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40formio/text-mask-addons
原文对照：https://npmcn.com/package/%40formio/text-mask-addons/?lang=original
项目主页：https://github.com/text-mask/text-mask/tree/master/addons/#readme
源码仓库：https://github.com/text-mask/text-mask

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：123 kB，23 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2022-09-13T19:29:20.228Z
- 最新版本发布：2024-11-15T21:48:54.712Z
- 近 30 天下载量：324169（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 0 个）

## 中文简介

文字遮盖加件 [https://github.com/text-mask/text-mask 页面存档备份,存于互联网档案馆](https://github.com/text-mask/text-mask)

## 安装

```sh
npm install @formio/text-mask-addons
```

也可以使用：`pnpm add @formio/text-mask-addons`、`yarn add @formio/text-mask-addons`、`bun add @formio/text-mask-addons`

## README

# 文字遮盖添加器

这些外加剂是随时可以使用的管子和口罩,可以和"文字面具"一起使用.

## 安装

```bash
npm i text-mask-addons --save
```

## 面具

这些可以作为一个 [`mask`](https://github.com/text-mask/text-mask/blob/master/componentDocumentation.md#mask) 改为文字面具.

### `createNumberMask`

`createNumberMask` 返回 a `numberMask` 函数将格式化用户输入为货币. `createNumberMask` 接受以下按键的对象:

1.  `prefix` (字符串):在金额之前要显示什么. 默认为 `'$'`。 。 。 .
2.  `suffix` (字符串):金额后要显示什么. 默认为空字符串 .
3.  `includeThousandsSeparator` (boolean):是否要分开上千个. 默认为 `true`。 。 。 .
4.  `thousandsSeparatorSymbol` (字符串):与它分开上千个字符. 默认为 `','`。 。 。 .
5.  `allowDecimal` (boolean):是否允许用户随金额输入分数. 默认为 `false`。 。 。 .
6.  `decimalSymbol` (字符串):将起到小数点作用的字符. 默认为 `'.'`
7.  `decimalLimit` (数字):小数后允许多少位数字。 默认为 `2`
8.  `integerLimit` (数字):限制整数的长度. 默认为 `null` 无限制
9.  `requireDecimal` (boolean):是否总是包括小数点和小数点的占位符 整数之后。 默认为 `false`。 。 。 .
10.  `allowNegative` (布尔):是否允许负数. 默认为 `false`
11.  `allowLeadingZeroes` (boolean):是否允许引导零。 默认为 `false`

#### 使用量

```js
import createNumberMask from 'text-mask-addons/dist/createNumberMask'

// First, you need to create the `numberMask` with your desired configurations
const numberMask = createNumberMask({
  prefix: '',
  suffix: ' $' // This will put the dollar sign at the end, with a space.
})

// ...then pass `numberMask` to the Text Mask component as the mask
```

### `emailMask`

`emailMask` 格式化用户输入为电子邮件地址.

#### 使用量

```js
import emailMask from 'text-mask-addons/dist/emailMask'

// ...then pass `emailMask` to the Text Mask component as the mask
```

_技术侧记_: 尽管 `emailMask` 作为 `mask`,它实际上是由两个 `mask` (单位:千美元) `pipe` 捆绑 一起为方便. 文本遮罩组件知道如何解开并分离 `pipe` 财务报告和审定财务报表 `mask` 函数来使用它们.

## 管道

这里的这些功能可以作为一个 [`pipe`](https://github.com/text-mask/text-mask/blob/master/componentDocumentation.md#pipe) 改为文字面具.

### `createAutoCorrectedDatePipe`

这个 `createAutoCorrectedDatePipe` 返回 a `autoCorrectedDatePipe`,可以帮助用户输入日期. 这个 `createAutoCorrectedDatePipe` 接受指定日期格式的字符串和带有以下密钥的对象:

1.  `minYear` (数目):日期栏允许的最低年数 `mask`。 。 。 .
2.  `maxYear` (数目):日期字段中允许的最大年份 `mask`。 。 。 .

例如,如果用户输入一个值 大于 `1` 在每月的第一个时段,它附加 `0` 对它。 这是 `4` => `04`。它做类似的事情 对于 白天档.

它还阻止用户输入无效天数或月份, 如 `33/44`。 。 。 .

对于 `createAutoCorrectedDatePipe` 文本遮罩组件需要 配置为 [`keepCharPositions`](https://github.com/text-mask/text-mask/blob/master/componentDocumentation.md#keepcharpositions) 设置为 `true`。 。 。 .

#### 使用量

```js
import createAutoCorrectedDatePipe from 'text-mask-addons/dist/createAutoCorrectedDatePipe'

const autoCorrectedDatePipe = createAutoCorrectedDatePipe('mm/dd/yyyy HH:MM')
// As you can see in the line above, you can pass a string argument to `createAutoCorrectedDatePipe` 
// to give it the order of day, month, year, hour and minute in your `mask`.

// ...now you can pass `autoCorrectedDatePipe` to the Text Mask component as the `pipe`
```

## 常见问题

### @formio/text-mask-addons 是什么？

文字遮盖加件 https://github\.com/text-mask/text-mask 页面存档备份,存于互联网档案馆

### 如何安装 @formio/text-mask-addons？

在项目目录运行 npm install @formio/text-mask-addons，或使用 pnpm add / yarn add / bun add。

### @formio/text-mask-addons 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @formio/text-mask-addons 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @formio/text-mask-addons 可以商用吗？

@formio/text-mask-addons 使用 Unlicense 许可。作者将代码贡献到公共领域，可不受限制地使用。以上为概括，不构成法律意见，请以许可原文为准。

### @formio/text-mask-addons 的下载量有多少？

根据 npm 官方下载统计，@formio/text-mask-addons 在 2026/10/16 – 2026/11/14 这 30 天内被下载 324,169 次，日均约 10,806 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @formio/text-mask-addons 还在维护吗？

最新版本 3\.8\.0-formio\.4 发布于 2024/11/16（2 年前）；至今共发布 3 个版本，其中过去 12 个月发布了 0 个；首次发布于 2022/09/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。