PinField 密码输入框 - Docs - Artefact

PinField 密码输入框

Forms

智能自动检测

Introduction

一个交互式分段输入控件，专为输入简短、固定长度的字母数字字符串而设计，例如验证码、一次性密码（OTP）、短信登录令牌和 PIN 值。它具有自动光标焦点循环、退格回删、粘贴净化以及完全统一的无障碍描述符。

PinField 组件已作为 pinField 区块完全集成到 Page Builder 中，使内容作者和开发人员能够直接在 CMS 中轻松配置代码长度、验证格式和输入状态。

Usage

以下示例展示了内容编辑人员如何绑定和构建自定义 PIN 输入组件。

1. 标准 6 位短信验证码输入

配置了 6 个分段框的标准数字 PIN 输入，针对电子邮件或短信验证码进行了优化。

{
  "type": "pinField",
  "label": "Verification code",
  "helperText": "Enter the 6-digit confirmation code we sent to your address.",
  "count": 6,
  "otp": true,
  "blurOnComplete": true,
  "interactive": true
}

Verification code

Enter the 6-digit confirmation code we sent to your address.

2. 安全隐藏密码输入（4 位）

展示一个安全的 4 位 PIN 模块。设置 mask 属性可通过用通用安全项目符号字形替换字符来保护输入。

{
  "type": "pinField",
  "label": "Security PIN",
  "placeholder": "•",
  "count": 4,
  "mask": true,
  "interactive": true
}

Security PIN

3. 自定义字母数字促销码（flushed 变体）

使用字母数字格式和独特的 flushed 边框变体渲染 5 个框的验证码选择器。

{
  "type": "pinField",
  "label": "Promo Coupon Code",
  "placeholder": "-",
  "count": 5,
  "format": "alphanumeric",
  "variant": "flushed",
  "interactive": true
}

Promo Coupon Code

Props

属性	CMS 字段类型	默认值	描述 / 支持的选项
标签文本 (`label`)	`string`	-	显示在输入分段上方的视觉主标题。
辅助文本 (`helperText`)	`string`	-	显示在输入框下方描述性说明文字。
错误信息 (`errorText`)	`string`	-	当代码条目未通过校验器检查时显示的验证消息。
框数量 (`count`)	`number`	`4`	要生成的输入分段框数量。
字符类型 (`format`)	`select`	`"numeric"`	限制可接受的字符。 • 选项：`"numeric"`、`"alphanumeric"`、`"alphabetic"`。
字符掩码 (`mask`)	`boolean`	`false`	勾选后，将输入值替换为安全项目符号以保护密码输入。
OTP 自动填充 (`otp`)	`boolean`	`false`	在移动设备上启用一次性代码自动填充检测。
自动提交 (`autoSubmit`)	`boolean`	`false`	最后一个分段填满时立即提交外层表单。
视觉变体 (`variant`)	`select`	`"outline"`	每个框的视觉样式。 • 选项：`"outline"`、`"subtle"`、`"surface"`、`"flushed"`。
尺寸比例 (`size`)	`select`	`"md"`	控制输入框的宽高。 • 选项：`"xs"`、`"sm"`、`"md"`、`"lg"`、`"xl"`。
强制交互 (`interactive`)	`boolean`	`true`	对代码字段元素进行注水，以绑定标签触发与粘贴净化。

Developer Notes & Accessibility

注水孤岛： 作为一个捕获粘贴事件、净化条目并处理移动端焦点边界上多输入光标跳转的高级布局，PinField 作为 Tier-2 条件性孤岛运行（"interactive": true）。
WAI-ARIA 合规性： 组件为每个分段输入框包裹了适当的布局与标签（role="group"、aria-label）。用户可以使用左右方向键或退格键在分段之间无缝切换。
表单集成： 它包含一个原生的隐藏 <input>，携带完整的拼接密码字符串。自动提交规则在输入完成后调用 form.requestSubmit()，无缝地将操作提交到最近的父表单。

FileUpload 文件上传

RadioCardGroup 单选卡片组

外观

外观

外观

外观