103 lines
5.3 KiB
JSON
103 lines
5.3 KiB
JSON
{
|
||
"slug": "checkbox",
|
||
"end": "react",
|
||
"curated": true,
|
||
"summary": "React 端复选框组：modelValue 是选中值数组，onChange 回传单个被切换项的 value，整组受控。",
|
||
"usage": [
|
||
"入参解构为 { modelValue = [], options = [], disabled = false, children, onChange, ... }，其中只有 modelValue/options/disabled/onChange 被消费（Checkbox.jsx:4）。",
|
||
"选项数据形如 [{ label, value }]；options 为空时用组件内置的「选项 A/B」两条兜底（Checkbox.jsx:5）。",
|
||
"勾选判断是 Array.isArray(modelValue) && modelValue.includes(o.value)，因此 modelValue 必须是数组而不是布尔（Checkbox.jsx:8）。",
|
||
"onChange 的载荷是「被点那一项的 value」而不是整个新数组：父组件要自己 toggle，示例里的 toggle 用 filter 或 concat 重算（Checkbox.jsx:8；示例 checkbox-ex-1）。",
|
||
"每项渲染成 <label class=\"kole-checkbox-option\"> 包一个 native input，name 固定为字符串 'kole-checkbox-group'，整组用 role=\"group\" 声明（Checkbox.jsx:7-8）。",
|
||
"外层多包了一个 .kole-checkbox-root，类名表里它是本端专有的容器层，CSS 中不存在同名规则（Checkbox.jsx:7）。"
|
||
],
|
||
"bestPractices": [
|
||
"onChange 只给 value，不做增删；不接 onChange 时复选框点了也不会变（受控且值不变），这是最常见的「点了没反应」原因（Checkbox.jsx:8）。",
|
||
"签名里的 children 与 onClick/onClose/onSubmit/onLoadMore 都没有绑定点，传了不生效、也不报错，不要据它们做逻辑（Checkbox.jsx:4,7-8）。",
|
||
"禁用是整组生效的（disabled 直接透传到每个 input），不支持逐项禁用；单项禁用需要绕过组件自己写结构（Checkbox.jsx:4,8）。",
|
||
"「支持全选和半选」在实现里没有对应能力：既没有全选框，也没有对 input.indeterminate 的赋值（Checkbox.jsx:7-8；契约契约 usage 提到但与实现不符）。"
|
||
],
|
||
"apiCarrier": {
|
||
"kind": "props",
|
||
"note": "React 端 API 是四个被消费的 props：modelValue 是选中值数组、options 是选项数据、disabled 整组禁用、onChange 回传被切换项的 value；签名里另有 children 与四个未绑定回调。",
|
||
"table": [
|
||
{
|
||
"name": "modelValue",
|
||
"type": "Array，默认 []",
|
||
"desc": "已选中的 value 数组，用 includes 判断每项是否勾选"
|
||
},
|
||
{
|
||
"name": "options",
|
||
"type": "Array<{ label, value }>，默认 []",
|
||
"desc": "选项数据；为空时回落到内置的选项 A/B 两条"
|
||
},
|
||
{
|
||
"name": "disabled",
|
||
"type": "boolean，默认 false",
|
||
"desc": "整组禁用，直接透传给每个 input 的 disabled"
|
||
},
|
||
{
|
||
"name": "onChange",
|
||
"type": "(value: string) => void",
|
||
"desc": "某一项被切换时调用，载荷是被点项的 value（不是新数组）"
|
||
},
|
||
{
|
||
"name": "children",
|
||
"type": "ReactNode",
|
||
"desc": "签名中声明，实现里未被渲染，传入无效"
|
||
},
|
||
{
|
||
"name": "kole-checkbox-root",
|
||
"type": "className",
|
||
"desc": "最外层容器类名（本端专有，CSS 中无同名规则）"
|
||
},
|
||
{
|
||
"name": "kole-checkbox",
|
||
"type": "className",
|
||
"desc": "分组容器类名，与 role=\"group\" 同节点"
|
||
},
|
||
{
|
||
"name": "kole-checkbox-option",
|
||
"type": "className",
|
||
"desc": "每项 label 的类名"
|
||
},
|
||
{
|
||
"name": "name",
|
||
"type": "原生属性",
|
||
"desc": "固定为 'kole-checkbox-group'，作原生表单分组名"
|
||
}
|
||
]
|
||
},
|
||
"a11y": [
|
||
"分组容器带 role=\"group\"，但没有 aria-label 或 aria-labelledby，组名缺失；建议在业务侧包一层带标题的 fieldset 或补 aria-label（Checkbox.jsx:8）。",
|
||
"勾选控件是原生 <input type=\"checkbox\">，空格切换与 Tab 聚焦由浏览器提供，不需要自建键盘处理（Checkbox.jsx:8）。",
|
||
"文字在 label 内、input 之后，控件可访问名称即该文字（如「邮件通知」），标签与控件无需 id 关联（Checkbox.jsx:8）。",
|
||
"disabled 走原生属性，读屏器会把选项播报为不可用；整组禁用时只是变灰，没有额外说明文字（Checkbox.jsx:8）。"
|
||
],
|
||
"resources": [
|
||
{
|
||
"file": "frameworks/Checkbox.jsx",
|
||
"kind": "React 组件",
|
||
"desc": "Checkbox.jsx —— React 实现：四个被消费的 props、受控勾选判断与 role=\"group\" 结构"
|
||
},
|
||
{
|
||
"file": "frameworks/Checkbox.css",
|
||
"kind": "样式文件",
|
||
"desc": "Checkbox.css —— 组件 import 的 .kole-checkbox 系列类与禁用态样式"
|
||
}
|
||
],
|
||
"exampleIds": [
|
||
"checkbox-ex-1",
|
||
"checkbox-ex-2"
|
||
],
|
||
"notes": [
|
||
"props 解构一行：frameworks/Checkbox.jsx:4",
|
||
"选项兜底与渲染：frameworks/Checkbox.jsx:5,8",
|
||
"勾选判断与 onChange 载荷：frameworks/Checkbox.jsx:8",
|
||
"role=\"group\" 与固定 name：frameworks/Checkbox.jsx:8",
|
||
"禁用态样式（与 [disabled] 合并）：frameworks/Checkbox.css:13",
|
||
"组件 import 了 useState（frameworks/Checkbox.jsx:1）但未使用，说明该端是受控桩：内部无状态。",
|
||
"consumedApi.emits 里的 onClick/onClose/onSubmit/onLoadMore 与 props 中的 children 均无绑定点，已在 table 中标注。"
|
||
]
|
||
}
|