# @danil321654/react-input-mask 中文文档

规范地址：https://npmcn.com/package/%40danil321654/react-input-mask/

版本：3\.0\.8
npm 元数据更新时间：2025-05-23T14:42:03.047Z
中文译文更新时间：2026-11-11T10:49:29.974Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40danil321654/react-input-mask
原文对照：https://npmcn.com/package/%40danil321654/react-input-mask/?lang=original
项目主页：https://github.com/sanniassin/react-input-mask
源码仓库：https://github.com/sanniassin/react-input-mask

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

- 包体积（解压后）：111 kB，8 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：2 个
- peer 依赖：react \>=0\.14\.0，react-dom \>=0\.14\.0
- 首次发布：2025-05-03T09:43:48.447Z
- 最新版本发布：2025-05-23T14:42:02.875Z
- 近 30 天下载量：3598（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 0 个）

## 中文简介

装入输入组件进行反射

## 安装

```sh
npm install @danil321654/react-input-mask
```

也可以使用：`pnpm add @danil321654/react-input-mask`、`yarn add @danil321654/react-input-mask`、`bun add @danil321654/react-input-mask`

## README

# 反应-输入-任务

[![Build Status](https://img.shields.io/travis/sanniassin/react-input-mask/master.svg?style=flat)](https://travis-ci.org/sanniassin/react-input-mask) [![npm version](https://img.shields.io/npm/v/react-input-mask.svg?style=flat)](https://www.npmjs.com/package/react-input-mask) [![npm downloads](https://img.shields.io/npm/dm/react-input-mask.svg?style=flat)](https://www.npmjs.com/package/react-input-mask)

React 的输入遮盖组件 。 注意了UX系统 与IE8+兼容.

#### [演示](http://sanniassin.github.io/react-input-mask/demo.html)

# 目录

-   [安装](https://npmcn.com/package/%40danil321654/react-input-mask/#readme-install)
-   [属性](https://npmcn.com/package/%40danil321654/react-input-mask/#readme-properties)
-   [实例](https://npmcn.com/package/%40danil321654/react-input-mask/#readme-examples)
-   [已知问题](https://npmcn.com/package/%40danil321654/react-input-mask/#readme-known-issues)

# 安装

`npm install react-input-mask --save`

也可以不用模块捆绑器

```html
<!-- Load React first -->
<script src="https://unpkg.com/react/dist/react.min.js"></script>
<script src="https://unpkg.com/react-dom/dist/react-dom.min.js"></script>
<!-- Will be exported to window.ReactInputMask -->
<script src="https://unpkg.com/react-input-mask/dist/react-input-mask.min.js"></script>
```

# 属性

### `mask` 数字 : `string`

口罩绳. 默认格式字符为:  
`9`数字 : `0-9`  
`a`数字 : `A-Z, a-z`  
`*`数字 : `A-Z, a-z, 0-9`

任何角色都可以用回击来逃脱. 在联署材料中,这将成为双重反弹。 例如,一个带有不可移动前缀+49的德国电话口罩将看起来像 `mask="+4\9 99 999 99"` 或者说 `mask={'+4\\9 99 999 99'}`

### `maskChar` 数字 : `string`

覆盖口罩未填充部分的字符 。 默认字符为" ". 如果设置为无效或空字符串,未填充的部分将像普通输入一样为空.

### `formatChars` 数字 : `object`

定义以字符为键的格式字符,以对应的RegExp字符串为值. 默认 :

```js
{
  '9': '[0-9]',
  'a': '[A-Za-z]',
  '*': '[A-Za-z0-9]'
}
```

### `alwaysShowMask` 数字 : `boolean`

当输入为空且没有焦点时显示掩码 .

### `inputRef` 数字 : `function`

使用 `inputRef` 改为 `ref` 如果您需要输入节点来管理焦点、选择等.

## 实验: 火:

以下道具被认为是实验性的,因为它们更容易出问题并有可能在未来被改变. 谨慎使用.

### `beforeMaskedValueChange` 数字 : `function`

如果你需要实施更复杂的伪装行为,你可以提供 `beforeMaskedValueChange` 函数可以更改被遮蔽的值和光标位置,然后应用到输入中. `beforeMaskedValueChange` 接收以下参数:

1.  **新状态** (对象):新输入状态. 包含 `value` 财务报告和审定财务报表 `selection` 字段. `selection` 对输入模糊或当在输入上架前调用函数时无效。 示例 `{ value: '12/1_/____', selection: { start: 4, end: 4 } }`
2.  **旧状态** (对象):变化前输入状态. 包含 `value` 财务报告和审定财务报表 `selection` 字段. `selection` 对于输入焦点或当在输入上架前调用函数时,则无效.
3.  **用户输入** (字符串):原始输入或粘接字符串. `null` 如果用户没有输入任何东西(例如由于道具更改而被删除或重新收发所触发).
4.  **遮罩选项** (对象):口罩选项. 示例

```js
{
  mask: '99/99/9999',
  maskChar: '_',
  alwaysShowMask: false,
  formatChars: {
    '9': '[0-9]',
    'a': '[A-Za-z]',
    '*': '[A-Za-z0-9]'
  },
  permanents: [2, 5] // permanents is an array of indexes of the non-editable characters in the mask
}
```

`beforeMaskedValueChange` 对象必须返回以下字段:

1.  **价值** (字符串):新值.
2.  **选择** (对象):新选择. 若为 `selection` 内 `newState` 论据无效,也必须无效.

请注意: `beforeMaskedValueChange` 执行次数多于 `onChange` 并必须是纯洁的.

### `children` 数字 : `function`

**注:为使这一特点更加可靠,请说明贵国在下列情况下的使用情况: [这个问题](https://github.com/sanniassin/react-input-mask/issues/139)**

使用另一个组件而不是常规 `<input />` 传票作为孩子的功能。 函数收到 `props` 包含不为反应-输入-掩体内部使用道具的参数。 也就是说,除了以下的道具以外,每一道道具都通过: `onChange`, (中文(简体) ), `onPaste`, (中文(简体) ), `onMouseDown`, (中文(简体) ), `onFocus`, (中文(简体) ), `onBlur`, (中文(简体) ), `value`, (中文(简体) ), `disabled`, (中文(简体) ), `readOnly`。这些属性如果使用的话,应该总是直接传递给反应-输入-掩码而不是孩子,不应该改变chldren的功能.

```jsx
import React from 'react';
import InputMask from 'react-input-mask';
import MaterialInput from '@material-ui/core/Input';

// Will work fine
const Input = (props) => (
  <InputMask mask="99/99/9999" value={props.value} onChange={props.onChange}>
    {(inputProps) => <MaterialInput {...inputProps} type="tel" disableUnderline />}
  </InputMask>
);

// Will throw an error because InputMask's and children's onChange aren't the same
const InvalidInput = (props) => (
  <InputMask mask="99/99/9999" value={props.value}>
    {(inputProps) => <MaterialInput {...inputProps} type="tel" disableUnderline onChange={props.onChange} />}
  </InputMask>
);
```

# 实例

```jsx
import React from 'react';
import InputMask from 'react-input-mask';

class PhoneInput extends React.Component {
  render() {
    return <InputMask {...this.props} mask="+4\9 99 999 99" maskChar=" " />;
  }
}
```

ZIP码的口罩. 在MaskedValue Change之前, 如果用户没有输入则省略后缀:

```jsx
import React from 'react';
import InputMask from 'react-input-mask';

class Input extends React.Component {
  state = {
    value: ''
  }

  onChange = (event) => {
    this.setState({
      value: event.target.value
    });
  }

  beforeMaskedValueChange = (newState, oldState, userInput) => {
    var { value } = newState;
    var selection = newState.selection;
    var cursorPosition = selection ? selection.start : null;

    // keep minus if entered by user
    if (value.endsWith('-') && userInput !== '-' && !this.state.value.endsWith('-')) {
      if (cursorPosition === value.length) {
        cursorPosition--;
        selection = { start: cursorPosition, end: cursorPosition };
      }
      value = value.slice(0, -1);
    }

    return {
      value,
      selection
    };
  }

  render() {
    return <InputMask mask="99999-9999" maskChar={null} value={this.state.value} onChange={this.onChange} beforeMaskedValueChange={this.beforeMaskedValueChange} />;
  }
}
```

# 已知问题

### 自动填充

浏览器的自动填充需要输入中的空值或完全匹配自动填充值开头的值。 一,即自动填充值"+1(555)123-4567"将与"+1"或"+1"(5)相通,但不会与"+1(-)---"或"1(555)"相通. 有几种可能的解决办法:

1.  设定 `maskChar` 将“+1”后空格改为空格 `beforeMaskedValueChange` 如果没有再输入数字.
2.  仅在值不为空时应用掩码 。 一般来说,这是最可靠的解决方案,因为我们无法确定自动填充值的格式.
3.  在口罩中使用较少格式化.

请注意,这可能导致用户体验更差(如果输入为空,我是否应该输入+1?). 你应该选择对用户更为重要的内容——平滑打字体验或自动填充. 电话和ZIP代码输入极有可能被自动填充,而关心这个问题是一个好主意,而两个要素授权中的安全确认代码则根本不应该考虑自动填充.

# 谢谢

感谢 [浏览器Stack](https://www.browserstack.com/) 帮助在真实设备上进行测试

## 常见问题

### @danil321654/react-input-mask 是什么？

装入输入组件进行反射

### 如何安装 @danil321654/react-input-mask？

在项目目录运行 npm install @danil321654/react-input-mask，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=0\.14\.0）、react-dom（\>=0\.14\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @danil321654/react-input-mask 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/danil321654\_\_react-input-mask 是否存在。

### @danil321654/react-input-mask 支持 ESM 还是 CommonJS？

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

### @danil321654/react-input-mask 可以商用吗？

@danil321654/react-input-mask 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @danil321654/react-input-mask 的下载量有多少？

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

### @danil321654/react-input-mask 还在维护吗？

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