82 lines
3.6 KiB
JSON
82 lines
3.6 KiB
JSON
{
|
||
"slug": "cascader",
|
||
"end": "react",
|
||
"curated": true,
|
||
"summary": "React 端级联选择器：单选存一条路径数组，多选存路径数组的数组，带搜索与逐级展开。",
|
||
"usage": [
|
||
"单选时 value 是一条路径数组，多选时是路径数组的数组；判重统一用 JSON.stringify 比较路径，所以路径元素需保持可序列化。",
|
||
"展开层级由 activePath state 记录，每次点某一列都会用 activePath.slice(0, lv) 截断再拼上新值，右侧列随之重算。",
|
||
"多选只在叶子节点出现勾选框，源码用 multiple && !n.children 判断，父节点点击仅用于换列。",
|
||
"输入搜索词时 results 由 allLeaves 过滤得到，匹配依据是整条路径 label 拼成字符串后 includes，搜索态与逐级浏览态共用同一面板。",
|
||
"commit 与 choose 都由内部函数改写值后调 onChange，受控判断与 ListPicker 相同：value 传入即不自持状态。"
|
||
],
|
||
"bestPractices": [
|
||
"判重依赖 JSON.stringify 的结果，选项路径里不能放函数或循环引用，否则比较恒为 false 导致重复选中。",
|
||
"多选值类型是数组的数组，onChange 回传的也是它，消费方要按 value.some 逐路径比对而不是 includes。",
|
||
"切换单选与多选会改变 value 的形状，不要在同一实例上动态切 multiple，数据形状与渲染分支会同时对不上。"
|
||
],
|
||
"apiCarrier": {
|
||
"kind": "props",
|
||
"note": "React 端 6 个 props、唯一回调 onChange；展开层级 activePath 与搜索词 query 是内部 state。",
|
||
"table": [
|
||
{
|
||
"name": "value",
|
||
"type": "Array（受控）",
|
||
"desc": "单选为路径数组，多选为路径数组的数组；传入即受控"
|
||
},
|
||
{
|
||
"name": "defaultValue",
|
||
"type": "Array，默认 []",
|
||
"desc": "非受控初始值，作为 useState 初值使用"
|
||
},
|
||
{
|
||
"name": "options",
|
||
"type": "Array，树形",
|
||
"desc": "每项形如 {value,label,children?}，children 存在即还能继续下钻"
|
||
},
|
||
{
|
||
"name": "multiple",
|
||
"type": "Boolean",
|
||
"desc": "是否多选，仅在叶子节点渲染勾选框"
|
||
},
|
||
{
|
||
"name": "filterable",
|
||
"type": "Boolean",
|
||
"desc": "是否显示搜索输入与匹配结果列表"
|
||
},
|
||
{
|
||
"name": "onChange",
|
||
"type": "(value) => void",
|
||
"desc": "选中或取消后回调，参数形状随 multiple 变化"
|
||
}
|
||
]
|
||
},
|
||
"a11y": [
|
||
"触发器是 div 加 onClick，无 tabindex 与 role，键盘无法进入级联面板。",
|
||
"各级选项是 div 加 onClick，没有 role=treeitem 或 aria-expanded，正在展开哪一级、还有没有子级都读不出来。",
|
||
"多选勾选框只是 span.box 里的 ✓ 文本，缺 role=checkbox 与 aria-checked。"
|
||
],
|
||
"resources": [
|
||
{
|
||
"file": "frameworks/Cascader.jsx",
|
||
"kind": "React 实现",
|
||
"desc": "Cascader.jsx —— 本端实现全文，含结构与交互逻辑"
|
||
},
|
||
{
|
||
"file": "frameworks/Cascader.css",
|
||
"kind": "样式文件",
|
||
"desc": "frameworks/Cascader.css —— 组件全部 kole-* 类名与 is-* 状态类的样式定义"
|
||
}
|
||
],
|
||
"exampleIds": [
|
||
"cascader-ex-1",
|
||
"cascader-ex-2"
|
||
],
|
||
"notes": [
|
||
"props 声明与形状说明见 frameworks/Cascader.jsx:16-25，受控判断在第 27 行。",
|
||
"逐级展开见 frameworks/Cascader.jsx:41-52，叶子勾选判定见第 130 行与第 133 行。",
|
||
"搜索匹配集 allLeaves 见 frameworks/Cascader.jsx:54-65。",
|
||
"组件自带用法示例注释见 frameworks/Cascader.jsx:147-152。"
|
||
]
|
||
}
|