106 lines
5.3 KiB
JSON
106 lines
5.3 KiB
JSON
{
|
||
"slug": "layoutswitcher",
|
||
"end": "react",
|
||
"curated": true,
|
||
"summary": "React 端布局切换器：value 表示当前布局，点任一选项经 onChange 回传该布局的 value，选中态由 value 比对得出。",
|
||
"usage": [
|
||
"唯一入参是 { value = 'side', onChange }，选中判断写在渲染里：value === o.value 才拼上 is-active 类（LayoutSwitcher.jsx:10,16）。",
|
||
"三个选项来自模块内常量 OPTIONS，值为 side / top / mixed，标签是「侧边布局 / 顶部布局 / 混合布局」；组件不接受外部传选项列表（LayoutSwitcher.jsx:4-8）。",
|
||
"点击只做一件事：onClick={() => onChange && onChange(o.value)}，自身不保存状态，当前值完全由父组件控制（LayoutSwitcher.jsx:17）。",
|
||
"缩略图按布局条件渲染：o.value !== 'side' 才输出 .s-top，o.value !== 'top' 才输出 .s-side，混合布局两项都出现（LayoutSwitcher.jsx:20-24）。",
|
||
"组件没有内建默认选中逻辑：不传 value 时用默认 'side'，所以「第一项亮着」是默认值的效果而不是自动同步（LayoutSwitcher.jsx:10,16）。",
|
||
"用法示例是 <KoleLayoutSwitcher value={layout} onChange={setLayout} /> 的受控组合，事件载荷是字符串而非事件对象（LayoutSwitcher.jsx:10,17）。"
|
||
],
|
||
"bestPractices": [
|
||
"这是纯受控组件：不接 onChange 时点击没有任何反应，也不会自己切换高亮（LayoutSwitcher.jsx:17）。",
|
||
"选项列表写死在模块里，要扩展「折叠布局」这类第四项需要改源码；若确实需要动态选项，本端没有对应 prop（LayoutSwitcher.jsx:4-8）。",
|
||
"偏好持久化不在组件内：契约提到的「保存偏好」需要在 onChange 里落 localStorage 或后端，组件只管回传（LayoutSwitcher.jsx:17）。",
|
||
"选项 div 上没有 aria-checked 与键盘处理，只有 onClick；点击可用的同时也意味着键盘无法操作，接入时建议外层包真正的 radio 控件（LayoutSwitcher.jsx:16-17）。"
|
||
],
|
||
"apiCarrier": {
|
||
"kind": "props",
|
||
"note": "React 端 API 只有两个 props：value 是当前布局值（side/top/mixed），onChange 是点击回调并携带新值；组件无内部状态、无插槽、不转发 className 之类的剩余属性。",
|
||
"table": [
|
||
{
|
||
"name": "value",
|
||
"type": "'side' | 'top' | 'mixed'，默认 'side'",
|
||
"desc": "当前选中的布局，与选项值比对决定哪个加 is-active"
|
||
},
|
||
{
|
||
"name": "onChange",
|
||
"type": "(value: string) => void",
|
||
"desc": "点击某个选项时调用，载荷是该选项的 value"
|
||
},
|
||
{
|
||
"name": "kole-layoutsw",
|
||
"type": "className",
|
||
"desc": "选项容器类名"
|
||
},
|
||
{
|
||
"name": "kole-layoutsw-opt",
|
||
"type": "className",
|
||
"desc": "选项类名，选中时拼接 ' is-active'"
|
||
},
|
||
{
|
||
"name": "kole-layoutsw-mini",
|
||
"type": "className",
|
||
"desc": "缩略图框类名"
|
||
},
|
||
{
|
||
"name": "kole-layoutsw-label",
|
||
"type": "className",
|
||
"desc": "选项文字标签类名，内容取 OPTIONS 里的 label"
|
||
},
|
||
{
|
||
"name": "s-top",
|
||
"type": "className",
|
||
"desc": "顶部色块，非 side 布局时渲染"
|
||
},
|
||
{
|
||
"name": "s-body",
|
||
"type": "className",
|
||
"desc": "缩略图主体行，包住侧边与内容块"
|
||
},
|
||
{
|
||
"name": "s-side",
|
||
"type": "className",
|
||
"desc": "侧边色块，非 top 布局时渲染"
|
||
},
|
||
{
|
||
"name": "s-main",
|
||
"type": "className",
|
||
"desc": "内容区色块，三种布局都渲染"
|
||
}
|
||
]
|
||
},
|
||
"a11y": [
|
||
"选项目前是带 onClick 的 div：不可 Tab 聚焦、无 Enter/Space 处理，键盘用户无法切换布局（LayoutSwitcher.jsx:16-17）。",
|
||
"没有 role=\"radiogroup\"/role=\"radio\" 与 aria-checked，读屏器不知道这是三选一控件，也读不到选中项（LayoutSwitcher.jsx:12-28）。",
|
||
"选中态是视觉上的品牌色边框加光晕，没有任何 aria 或文本补充；如需无障碍等价信息，应在选项上加 aria-checked（LayoutSwitcher.css:5）。",
|
||
"选项文字是纯文本子节点，缩略图色块为装饰性 div 且无文本，读屏器只念出「侧边布局」这类标签，与视觉信息量一致（LayoutSwitcher.jsx:26）。"
|
||
],
|
||
"resources": [
|
||
{
|
||
"file": "frameworks/LayoutSwitcher.jsx",
|
||
"kind": "React 组件",
|
||
"desc": "LayoutSwitcher.jsx —— React 实现：OPTIONS 常量、受控 value 与 onChange 回调"
|
||
},
|
||
{
|
||
"file": "frameworks/LayoutSwitcher.css",
|
||
"kind": "样式文件",
|
||
"desc": "LayoutSwitcher.css —— 组件 import 的选项卡片与缩略图色块样式"
|
||
}
|
||
],
|
||
"exampleIds": [
|
||
"layoutswitcher-ex-1"
|
||
],
|
||
"notes": [
|
||
"props 解构与 default value：frameworks/LayoutSwitcher.jsx:10",
|
||
"OPTIONS 三项常量：frameworks/LayoutSwitcher.jsx:4-8",
|
||
"选中类拼接与点击回调：frameworks/LayoutSwitcher.jsx:16-17",
|
||
"缩略图条件渲染：frameworks/LayoutSwitcher.jsx:20-24",
|
||
"consumedApi.emits 里的 onClick 是绑在选项 div 上的处理器，不是对外 props，故未进 table。",
|
||
"契约 dims 的 collapsed 维度在本端无实现（OPTIONS 里没有折叠项），按实现写。"
|
||
]
|
||
}
|