125 lines
5.9 KiB
JSON
125 lines
5.9 KiB
JSON
{
|
||
"slug": "modal",
|
||
"end": "react",
|
||
"curated": true,
|
||
"summary": "受控对话框：open 决定显隐，onClose/onOk 是唯一出口，footer 可整块替换为自定义节点。",
|
||
"usage": [
|
||
"React 端显隐完全受控：传 open={open}，关闭必须自己接 onClose={() => setOpen(false)}，组件不会自行隐藏（Modal.jsx:12,25）。",
|
||
"源码首行就是 if (!open) return null（Modal.jsx:25），因此对话框只在打开时才挂载子树，内部表单状态每次打开都会重建。",
|
||
"底部按钮文案改成属性：okText / cancelText 默认「确定」「取消」，hideFooter 可整块去掉（Modal.jsx:18-19,41）。",
|
||
"需要自定义页脚就传 footer 节点，它会整体替换默认的两个 button（Modal.jsx:43-48）。",
|
||
"层级由 size 决定：small/default/large 拼成 kole-modal--{size} 类（Modal.jsx:14,33）。",
|
||
"遮罩点击关闭受 maskClosable 控制，且只在点击到遮罩自身时触发（Modal.jsx:27-29）。"
|
||
],
|
||
"bestPractices": [
|
||
"onOk 不会自动关闭对话框——源码里确定按钮只调 onOk（Modal.jsx:46），异步提交后请自行 setOpen(false)。",
|
||
"close 与 onClose 都表示关闭，但 closable 只控制右上角 × 的渲染（Modal.jsx:36），不阻止遮罩关闭。",
|
||
"弹窗内容依赖挂载时机的副作用要写在 children 组件自己的 useEffect 里，因为 !open 时整棵子树不存在。"
|
||
],
|
||
"apiCarrier": {
|
||
"kind": "props",
|
||
"note": "React 端的 API 载体是 props 与回调：属性驱动外观（type/size/disabled 等布尔与枚举），交互经 onXxx 回传（如 onChange/onClick/onSelectionChange）；没有 v-model，受控组件固定写成 value + onChange，非受控则用 defaultValue。",
|
||
"table": [
|
||
{
|
||
"name": "open",
|
||
"type": "boolean",
|
||
"desc": "是否显示；为 falsy 时直接返回 null 不渲染"
|
||
},
|
||
{
|
||
"name": "title",
|
||
"type": "string",
|
||
"desc": "标题文本，渲染在头部"
|
||
},
|
||
{
|
||
"name": "size",
|
||
"type": "'small' | 'default' | 'large'",
|
||
"desc": "尺寸，拼成 kole-modal--{size}"
|
||
},
|
||
{
|
||
"name": "closable",
|
||
"type": "boolean",
|
||
"desc": "是否渲染右上角关闭按钮"
|
||
},
|
||
{
|
||
"name": "maskClosable",
|
||
"type": "boolean",
|
||
"desc": "点击遮罩是否触发 onClose"
|
||
},
|
||
{
|
||
"name": "hideFooter",
|
||
"type": "boolean",
|
||
"desc": "隐藏整个底部区域"
|
||
},
|
||
{
|
||
"name": "okText",
|
||
"type": "string",
|
||
"desc": "确定按钮文案，默认「确定」"
|
||
},
|
||
{
|
||
"name": "cancelText",
|
||
"type": "string",
|
||
"desc": "取消按钮文案，默认「取消」"
|
||
},
|
||
{
|
||
"name": "footer",
|
||
"type": "ReactNode",
|
||
"desc": "自定义页脚，传入后替换默认按钮"
|
||
},
|
||
{
|
||
"name": "children",
|
||
"type": "ReactNode",
|
||
"desc": "对话框主体内容"
|
||
},
|
||
{
|
||
"name": "onClose",
|
||
"type": "() => void",
|
||
"desc": "关闭回调，遮罩与取消按钮共用"
|
||
},
|
||
{
|
||
"name": "onOk",
|
||
"type": "() => void",
|
||
"desc": "确定回调，不自动关闭"
|
||
}
|
||
]
|
||
},
|
||
"a11y": [
|
||
"对话框主体已标 role=\"dialog\"（Modal.jsx:33），但缺少 aria-modal=\"true\" 与 aria-labelledby，标题未与对话框建立可访问名关联。",
|
||
"关闭按钮带 aria-label=\"关闭\"（Modal.jsx:37），是带名字的按钮。",
|
||
"未实现焦点陷阱与 Esc 关闭，键盘用户可能把焦点 Tab 到背景内容；生产使用建议在业务侧补 Esc 监听与首焦点管理。"
|
||
],
|
||
"resources": [
|
||
{
|
||
"file": "frameworks/Modal.jsx",
|
||
"kind": "React（React）",
|
||
"desc": "React 端组件实现源码，props 与回调的唯一定义处"
|
||
},
|
||
{
|
||
"file": "frameworks/Modal.css",
|
||
"kind": "样式",
|
||
"desc": "该 React 实现依赖的样式文件"
|
||
}
|
||
],
|
||
"exampleIds": [
|
||
"modal-ex-1",
|
||
"modal-ex-2",
|
||
"modal-ex-3"
|
||
],
|
||
"notes": [
|
||
"frameworks/Modal.jsx:9 中可指到 open（boolean）——是否显示；为 falsy 时直接返回 null 不渲染",
|
||
"frameworks/Modal.jsx:13 中可指到 title（string）——标题文本，渲染在头部",
|
||
"frameworks/Modal.jsx:7 中可指到 size（'small' | 'default' | 'large'）——尺寸，拼成 kole-modal--{size}",
|
||
"frameworks/Modal.jsx:15 中可指到 closable（boolean）——是否渲染右上角关闭按钮",
|
||
"frameworks/Modal.jsx:16 中可指到 maskClosable（boolean）——点击遮罩是否触发 onClose",
|
||
"frameworks/Modal.jsx:17 中可指到 hideFooter（boolean）——隐藏整个底部区域",
|
||
"frameworks/Modal.jsx:19 中可指到 okText（string）——确定按钮文案，默认「确定」",
|
||
"frameworks/Modal.jsx:18 中可指到 cancelText（string）——取消按钮文案，默认「取消」",
|
||
"frameworks/Modal.jsx:22 中可指到 footer（ReactNode）——自定义页脚，传入后替换默认按钮",
|
||
"frameworks/Modal.jsx:23 中可指到 children（ReactNode）——对话框主体内容",
|
||
"frameworks/Modal.jsx:9 中可指到 onClose（() => void）——关闭回调，遮罩与取消按钮共用",
|
||
"frameworks/Modal.jsx:9 中可指到 onOk（() => void）——确定回调，不自动关闭",
|
||
"props 解构清单见 frameworks/Modal.jsx:11-24；本文件 table 只列该端真正消费的属性与回调。",
|
||
"过滤口径：事实包 consumedApi 里还包含绑在组件内部节点上的同名处理器（如 onClick/onChange 绑在内部 button、input、checkbox 上，见 frameworks/Modal.jsx 全文），它们不是对外 props，因此未进 table。",
|
||
"table 构成核验：12 行中 12 行是 frameworks/Modal.jsx 解构出的顶层 props（解构块 frameworks/Modal.jsx:11-24）；本组件 table 全部为顶层 props。"
|
||
]
|
||
}
|