116 lines
5.8 KiB
JSON
116 lines
5.8 KiB
JSON
{
|
||
"slug": "form",
|
||
"end": "react",
|
||
"curated": true,
|
||
"summary": "React 端的 Form：受控 label / required / error 三个 prop 加原生 form 提交，error 有值才渲染错误行。",
|
||
"usage": [
|
||
"提交走原生 form：`onSubmit={(e) => { e.preventDefault(); onSubmit && onSubmit(e); }}`，父组件拿到的是原生事件（要读 e.target.elements 自己取值）（frameworks/Form.jsx:8）。",
|
||
"error 是条件渲染：`{error ? <span className=\"kole-form-error\">{error}</span> : null}`，传空串则错误行整块消失，这也是示例里清空错误的方式（frameworks/Form.jsx:8）。",
|
||
"required 同时作用于两处：标签后的星号（`{label} {required ? <b aria-hidden=\"true\">*</b> : null}`）与原生 input 的 required 属性（frameworks/Form.jsx:8）。",
|
||
"输入框没有受控绑定：`<input className=\"kole-form-control\" name=\"name\" required={required} />` 无 value 也无 onChange，取值要靠提交事件里的 DOM 查询（frameworks/Form.jsx:8）。",
|
||
"提交与重置是两个原生按钮（type=\"submit\" / type=\"reset\"），重置由浏览器清空，组件不派发重置回调（frameworks/Form.jsx:8）。",
|
||
"fields / children / onChange / onClick / onClose / onLoadMore 都在解构里但未参与渲染（frameworks/Form.jsx:4）。"
|
||
],
|
||
"bestPractices": [
|
||
"字段是固定的单个 name 输入框：fields 数组不参与渲染，多字段表单要自己写结构（frameworks/Form.jsx:4,8）。",
|
||
"取值必须从提交事件里读（如 e.target.elements.name.value），组件不回传表单数据（frameworks/Form.jsx:8）。",
|
||
"原生 required 会先于 onSubmit 拦截空值：浏览器弹出原生气泡，业务自定义校验要在 error 里另做（frameworks/Form.jsx:8）。",
|
||
"error 只控制文案展示，不改变输入框的 aria-invalid 或边框，视觉错误态由 Form.css 决定（frameworks/Form.jsx:8）。"
|
||
],
|
||
"a11y": [
|
||
"label 包住 input 形成隐式关联，读屏器播报标签文字「名称」（frameworks/Form.jsx:8）。",
|
||
"必填星号标了 aria-hidden=\"true\"（frameworks/Form.jsx:8），读屏器不会读星号，但会通过原生 required 播报必填。",
|
||
"错误提示是普通 span，没有 role=\"alert\" 也没有 aria-describedby 关联到输入框，读屏器不会自动播报校验错误（frameworks/Form.jsx:8）。",
|
||
"提交与重置是真的 submit / reset 按钮，键盘回车可提交，符合表单惯例（frameworks/Form.jsx:8）。"
|
||
],
|
||
"apiCarrier": {
|
||
"kind": "props",
|
||
"note": "React 端的 API 载体是 props（label 标签文案、required 必填、error 校验文案）与 onSubmit 回调；输入框是非受控 DOM，值从提交事件里取，没有 v-model。",
|
||
"table": [
|
||
{
|
||
"name": "children",
|
||
"type": "属性",
|
||
"desc": "解构声明但 JSX 未渲染（frameworks/Form.jsx:4）"
|
||
},
|
||
{
|
||
"name": "error",
|
||
"type": "属性",
|
||
"desc": "校验错误文案，有值才渲染 .kole-form-error 行（frameworks/Form.jsx:4,8）"
|
||
},
|
||
{
|
||
"name": "fields",
|
||
"type": "Array",
|
||
"desc": "字段配置数组，声明默认空数组，JSX 无 map 未渲染（frameworks/Form.jsx:4,8）"
|
||
},
|
||
{
|
||
"name": "label",
|
||
"type": "属性",
|
||
"desc": "标签文字，渲染在 label 的 span 里，默认「名称」（frameworks/Form.jsx:4,8）"
|
||
},
|
||
{
|
||
"name": "onChange",
|
||
"type": "属性",
|
||
"desc": "解构声明但未绑定（frameworks/Form.jsx:4）"
|
||
},
|
||
{
|
||
"name": "onClick",
|
||
"type": "属性",
|
||
"desc": "解构声明但未绑定（frameworks/Form.jsx:4）"
|
||
},
|
||
{
|
||
"name": "onClose",
|
||
"type": "属性",
|
||
"desc": "解构声明但未绑定（frameworks/Form.jsx:4）"
|
||
},
|
||
{
|
||
"name": "onLoadMore",
|
||
"type": "属性",
|
||
"desc": "解构声明但未绑定（frameworks/Form.jsx:4）"
|
||
},
|
||
{
|
||
"name": "onChange",
|
||
"type": "事件",
|
||
"desc": "React 事件以 onXxx prop 命名；本实现未绑定 onChange（frameworks/Form.jsx:4）"
|
||
},
|
||
{
|
||
"name": "onClick",
|
||
"type": "事件",
|
||
"desc": "React 事件以 onXxx prop 命名；本实现未绑定 onClick（frameworks/Form.jsx:4）"
|
||
},
|
||
{
|
||
"name": "onClose",
|
||
"type": "事件",
|
||
"desc": "React 事件以 onXxx prop 命名；本实现未绑定 onClose（frameworks/Form.jsx:4）"
|
||
},
|
||
{
|
||
"name": "children",
|
||
"type": "插槽",
|
||
"desc": "React 无插槽语法，children 即默认子节点；本实现未渲染（frameworks/Form.jsx:4,8）"
|
||
}
|
||
]
|
||
},
|
||
"resources": [
|
||
{
|
||
"file": "frameworks/Form.jsx",
|
||
"kind": "React",
|
||
"desc": "该端实现（本页 API 与用法的唯一权威来源）。"
|
||
},
|
||
{
|
||
"file": "frameworks/Form.css",
|
||
"kind": "样式",
|
||
"desc": "该组件的样式文件，类名口径以它为准。"
|
||
}
|
||
],
|
||
"exampleIds": [
|
||
"form-ex-1",
|
||
"form-ex-2"
|
||
],
|
||
"notes": [
|
||
"props 解构见 frameworks/Form.jsx:4，共 10 个；渲染全在第 8 行（form / label / input / 错误行 / 双按钮）。",
|
||
"preventDefault 与 onSubmit 回调见 frameworks/Form.jsx:8；required 的两处影响（星号与原生属性）同在第 8 行。",
|
||
"a11y 依据：aria-hidden 星号、label 包裹式关联见 frameworks/Form.jsx:8；错误 span 无 role / aria-describedby。",
|
||
"实现缺口：输入框非受控、fields 未参与渲染、无重置回调（frameworks/Form.jsx:8）；按实现写，未发明表单模型。",
|
||
"apiCarrier.table 保留了自动生成时的「属性 + 事件 + 插槽」三套同名行（onChange / onClick / onClose / children 各两次），本次只改 desc 文案，未调整行结构。"
|
||
]
|
||
}
|