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, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/components/input-mask.md.

InputMask 格式输入

按照指定格式填写信息。

基本用法

原始值: —
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
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 时,可以导入这些类型。

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

InputMaskProps API

属性类型默认值说明
size'sm' | 'md' | 'lg''md'尺寸或间距预设
status'error' | 'warning'—显示状态
prefixReactNode—前置内容
suffixReactNode—后置内容
allowClearbooleanfalse显示清除按钮
onClear() => void—清除输入后触发
showCountboolean | ((value: string, maxLength?: number) => ReactNode)false显示字数,可自定义渲染
onPressEnterKeyboardEventHandler<HTMLInputElement>—按下 Enter 时触发
maskstring必填格式模式:0 为数字,a 为字母,* 为字母或数字
definitionsRecord<string, RegExp>—自定义格式字符规则
lazybooleantrue按需显示占位字符
unmaskbooleanfalse组件值与回调使用不含格式符的值
valuestring—受控值
defaultValuestring''初始值;非受控表单 reset 时恢复
onChange(value: string, formatted: string) => void—值变化回调
onComplete(value: string) => void—完整输入后触发