Semi Design中的PinCode验证码输入组件详解

原创于 2025-06-04 09:19:17 发布 · 227 阅读

CC 4.0 BY-SA版权

Semi Design中的PinCode验证码输入组件详解

semi-design 🚀A modern, comprehensive, flexible design system and React UI library. 🎨 Provide more than 2800+ Design Tokens, easy to build your design system. Make Semi Design to Any Design. 🧑🏻‍💻 Design to Code in one click 项目地址: https://gitcode.com/gh_mirrors/se/semi-design

什么是PinCode组件

PinCode是Semi Design提供的一个验证码输入组件，专门用于处理用户输入验证码的场景。它通过将验证码拆分为多个独立的输入框，为用户提供清晰直观的输入体验，同时内置了多种格式校验功能，确保用户输入符合预期的验证码格式。

核心特性

多尺寸支持：提供small、default、large三种尺寸选项
格式控制：可限制输入数字、字母或自定义字符
位数可配置：默认6位，可自由调整
事件回调：提供输入变化和完成输入的回调函数
受控/非受控：支持两种使用模式
聚焦控制：可通过API手动控制输入框焦点

基础使用

安装与引入

PinCode组件从2.62.0版本开始提供，使用时需要先引入：

import { PinCode } from '@douyinfe/semi-ui';

基本示例

function Demo() {
    return (
        <PinCode
            size={'default'}
            defaultValue={'123456'}
            onComplete={value => console.log('完成输入:', value)}
            onChange={value => console.log('输入变化:', value)}
        />
    );
}

进阶功能

受控模式

当需要完全控制组件状态时，可以使用受控模式：

function ControlledDemo() {
    const [value, setValue] = useState('');
    
    return (
        <PinCode
            value={value}
            onChange={v => setValue(v)}
            onComplete={v => console.log('验证码:', v)}
        />
    );
}

格式限制

PinCode提供了多种格式限制方式：

纯数字：format="number"
数字和字母：format="mixed"
正则表达式：format={/[A-Z]/}
自定义函数：format={char => /[a-z]/.test(char)}

<PinCode format="number" />  // 只允许数字
<PinCode format="mixed" />   // 允许数字和字母
<PinCode format={/[A-Z]/} /> // 只允许大写字母

位数配置

通过count属性可以设置验证码的位数：

<PinCode count={4} />  // 4位验证码
<PinCode count={6} />  // 默认6位

焦点控制

通过ref可以手动控制输入框的焦点：

function FocusDemo() {
    const ref = useRef();
    
    return (
        <>
            <Button onClick={() => ref.current.focus(2)}>聚焦第三个输入框</Button>
            <PinCode ref={ref} />
        </>
    );
}