81 lines
3.8 KiB
JSON
81 lines
3.8 KiB
JSON
{
|
||
"slug": "codeinput",
|
||
"end": "react",
|
||
"curated": true,
|
||
"summary": "React 端验证码输入：value 受控为字符串，内部拆成单元格，逐位自动跳格并支持回退与粘贴填充。",
|
||
"usage": [
|
||
"对外 API 是字符串 value，`内部用 buildCells 拆成等长数组渲染；每位输入后 join 回整串通过 onChange 抛出，不同步回写会让单元格停在上一次的值。",
|
||
"单元格状态放在 cells 里而非直接从 value 推导，value 只在 useState 初始化时读一次，所以受控使用要保证每次 onChange 都把新值回传。",
|
||
"输入时取 e.target.value.slice(-1) 只保留最后一位，并在非末位自动 focus(i + 1)。",
|
||
"退格分两级：当前格有字符就清空本格，已空则清上一格并把焦点前移，两条路径都会 preventDefault 以免原生行为再删一次。",
|
||
"左右方向键只移动焦点，不改变内容，索引边界在 length - 1 处截断。",
|
||
"粘贴在容器上处理：剥离非数字字符后按位填满，再把焦点落到最后一位有值的格子上。"
|
||
],
|
||
"bestPractices": [
|
||
"length 只在挂载时决定单元格数量，运行中改 length 不会重建 cells 数组，需要重新挂载或加 key。",
|
||
"hasError 只切换 tip 文本的 error 类，不改变输入框自身的边框或 aria-invalid。",
|
||
"粘贴时用正则在 text 上剥掉非数字，因此带空格或分隔符的验证码可以正常填入，但字母验证码会被清空。"
|
||
],
|
||
"apiCarrier": {
|
||
"kind": "props",
|
||
"note": "React 端 6 个 props 加 onChange 回调；值是字符串，分段单元格与焦点索引是内部 state（cells、focusedIndex），没有 v-model 式的双向绑定。",
|
||
"table": [
|
||
{
|
||
"name": "value",
|
||
"type": "String，默认空串",
|
||
"desc": "受控的完整验证码字符串，仅在挂载时用于初始化单元格"
|
||
},
|
||
{
|
||
"name": "length",
|
||
"type": "Number，默认 6",
|
||
"desc": "单元格位数，决定渲染几个输入框"
|
||
},
|
||
{
|
||
"name": "masked",
|
||
"type": "Boolean，默认 false",
|
||
"desc": "为真时给单元格叠加 is-masked，按掩码样式显示"
|
||
},
|
||
{
|
||
"name": "tip",
|
||
"type": "String",
|
||
"desc": "输入框下方提示文本，与 hasError 共同决定是否显示为错误态"
|
||
},
|
||
{
|
||
"name": "hasError",
|
||
"type": "Boolean，默认 false",
|
||
"desc": "为真时提示文本加 error 类"
|
||
},
|
||
{
|
||
"name": "onChange",
|
||
"type": "(code: String) => void",
|
||
"desc": "每次输入、退格或粘贴后回调，参数为拼接好的完整字符串"
|
||
}
|
||
]
|
||
},
|
||
"a11y": [
|
||
"每个输入框都带 aria-label 验证码第 N 位，读屏器能报出当前是第几位，这是本组件做得最好的一处。",
|
||
"输入框设了 inputMode=numeric 以唤起数字键盘，但没有 aria-invalid，错误态只体现在提示文本的样式上。",
|
||
"提示文本所在的 .kole-code-tip 没有 role=alert 或 aria-live，校验失败时读屏器不会主动播报。"
|
||
],
|
||
"resources": [
|
||
{
|
||
"file": "frameworks/CodeInput.jsx",
|
||
"kind": "React 实现",
|
||
"desc": "CodeInput.jsx —— 本端实现全文（结构、事件与状态逻辑）"
|
||
},
|
||
{
|
||
"file": "frameworks/CodeInput.css",
|
||
"kind": "样式文件",
|
||
"desc": "frameworks/CodeInput.css —— 本端 kole-* 类名与 is-* 状态类的样式定义"
|
||
}
|
||
],
|
||
"exampleIds": [
|
||
"codeinput-ex-1"
|
||
],
|
||
"notes": [
|
||
"props 与默认值见 frameworks/CodeInput.jsx:10-17，单元格拆分函数见第 4-8 行。",
|
||
"自动跳格见 frameworks/CodeInput.jsx:41，退格两级逻辑见第 46-56 行。",
|
||
"粘贴填充见 frameworks/CodeInput.jsx:64-73，逐位 aria-label 见第 94 行。"
|
||
]
|
||
}
|