> Leaf UI 0.8.1 · Package: @ifhover/leaf-ui · Source: 435bab23cad7d343653d9b63b049c0b0601eeefb
> Browser documentation: https://ifhover.github.io/leaf-ui/components/input-mask.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt.

# InputMask 格式输入

按照指定格式填写信息。

## 基本用法


原始值: —

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/input-mask/basic.tsx"
import { InputMask, Space, Text } from '@ifhover/leaf-ui';

import { useState } from 'react';

export function InputMaskBasic() {
  const [value, setValue] = useState('');
  return (
    <Space direction="vertical" align="stretch">
      <InputMask
        mask="+{86} 000 0000 0000"
        placeholder="+86 138 0000 0000"
        unmask
        value={value}
        onChange={setValue}
        aria-label="电话号码"
      />
      <output>
        <Text tone="muted">原始值: {value || '—'}</Text>
      </output>
    </Space>
  );
}
```

展开代码

## 更多用法


银行卡格式字母与数字规则

advanced.tsx

复制代码

```tsx lineNumbers file="../../src/examples/input-mask/advanced.tsx"
import { InputMask, Space, Text } from '@ifhover/leaf-ui';

export function InputMaskFormats() {
  return (
    <Space direction="vertical" align="stretch">
      <Text tone="muted">银行卡格式</Text>
      <InputMask mask="0000 0000 0000 0000" lazy={false} aria-label="卡号" />
      <Text tone="muted">字母与数字规则</Text>
      <InputMask
        mask="AA-0000"
        definitions={{ A: /[A-Z]/ }}
        placeholder="AB-1234"
        aria-label="编号"
      />
    </Space>
  );
}
```

展开代码

## 使用说明

格式字符 0 为数字、a 为字母、\* 为字母或数字。格式输入只限制字符形态，业务校验由应用处理。unmask 影响组件值与回调；原生表单提交显示值。

## 类型

组装数据、定义回调和使用 ref 时，可以导入这些类型。

```ts
import type { InputMaskProps } from '@ifhover/leaf-ui';
```

## InputMaskProps API

| 属性             | 类型                                                              | 默认值     | 说明                         |
| -------------- | --------------------------------------------------------------- | ------- | -------------------------- |
| `size`         | `'sm' \| 'md' \| 'lg'`                                          | `'md'`  | 尺寸或间距预设                    |
| `status`       | `'error' \| 'warning'`                                          | —       | 显示状态                       |
| `prefix`       | `ReactNode`                                                     | —       | 前置内容                       |
| `suffix`       | `ReactNode`                                                     | —       | 后置内容                       |
| `allowClear`   | `boolean`                                                       | `false` | 显示清除按钮                     |
| `onClear`      | `() => void`                                                    | —       | 清除输入后触发                    |
| `showCount`    | `boolean \| ((value: string, maxLength?: number) => ReactNode)` | `false` | 显示字数，可自定义渲染                |
| `onPressEnter` | `KeyboardEventHandler<HTMLInputElement>`                        | —       | 按下 Enter 时触发               |
| `mask`         | `string`                                                        | 必填      | 格式模式：0 为数字，a 为字母，\* 为字母或数字 |
| `definitions`  | `Record<string, RegExp>`                                        | —       | 自定义格式字符规则                  |
| `lazy`         | `boolean`                                                       | `true`  | 按需显示占位字符                   |
| `unmask`       | `boolean`                                                       | `false` | 组件值与回调使用不含格式符的值            |
| `value`        | `string`                                                        | —       | 受控值                        |
| `defaultValue` | `string`                                                        | `''`    | 初始值；非受控表单 reset 时恢复        |
| `onChange`     | `(value: string, formatted: string) => void`                    | —       | 值变化回调                      |
| `onComplete`   | `(value: string) => void`                                       | —       | 完整输入后触发                    |