@para-ui/core 5.0.0-beta.11 → 5.0.0-beta.13

package/lib/Tree/component.json

@@ -0,0 +1,512 @@
+{
+    "name": "Tree",
+    "category": "Data Display",
+    "description": "多层级数据的树形显示组件",
+    "semantic": {
+        "intent": [
+            "展示层级数据",
+            "文件夹管理",
+            "权限设置"
+        ],
+        "useCases": [
+            "文件系统",
+            "组织架构",
+            "权限树"
+        ],
+        "riskLevel": "high"
+    },
+    "variants": {
+        "default": {
+            "meaning": "标准树"
+        }
+    },
+    "states": [
+        "loading",
+        "empty"
+    ],
+    "idealProps": {
+        "treeData": {
+            "type": "array",
+            "itemSchema": {
+                "key": { "type": "string | number", "required": true, "description": "节点唯一标识（整个树范围内不能重复）" },
+                "title": { "type": "ReactNode", "description": "节点显示内容" },
+                "children": { "type": "DataNode[]", "description": "子节点" },
+                "disabled": { "type": "boolean", "description": "是否禁用节点" },
+                "disableCheckbox": { "type": "boolean", "description": "禁掉节点 Checkbox（不影响 selectable）" },
+                "selectable": { "type": "boolean", "description": "节点是否可被选中（覆盖组件级 selectable）" },
+                "checkable": { "type": "boolean", "description": "单节点是否可勾选（覆盖组件级 checkable）" },
+                "isLeaf": { "type": "boolean", "description": "是否叶子节点（loadData 场景标记已无下级，为 false 时强制作为父节点）" },
+                "icon": { "type": "ReactNode | (props: TreeNodeProps) => ReactNode", "description": "自定义节点图标" }
+            },
+            "description": "树形数据源（嵌套 children 结构）；若用 replaceFields.parentId 则可传扁平结构由组件内部 convert；key 在整个树内必须唯一"
+        },
+        "url": {
+            "type": "string",
+            "description": "远程数据接口地址。⚠️ 触发条件：必须同时传 asyncLoad={true} 组件才会内部 fetch + 填充 treeData；只传 url 不传 asyncLoad 不会触发请求。返回格式支持嵌套 children 或扁平 parentId（扁平需配合 replaceFields.parentId）；可通过 requestCallback 对响应预处理"
+        },
+        "checkable": {
+            "type": "boolean",
+            "default": false,
+            "description": "节点前添加 Checkbox 多选"
+        },
+        "checkedKeys": {
+            "type": "React.Key[] | { checked: React.Key[]; halfChecked: React.Key[] }",
+            "description": "（受控）选中复选框节点；checkStrictly=true 时第二种结构父子选中状态不再关联。注：string 是 React.Key 的子集，业务侧 string[] 可直接传入"
+        },
+        "defaultCheckedKeys": {
+            "type": "React.Key[]",
+            "default": "[]",
+            "description": "默认选中复选框的树节点（非受控初始值，受控时以 checkedKeys 为准）",
+            "_src": "src/Tree/interface.ts:63 defaultCheckedKeys?: Key[]"
+        },
+        "onCheck": {
+            "type": "function",
+            "signature": "(checkedKeys: React.Key[], info: unknown, halfCheckedKeys?: React.Key[]) => void",
+            "description": "点击复选框触发（src/Tree/interface.ts:126）；第 1 参数为已勾选节点 Key[]；第 2 参数 info 为内部实现细节（类型 unknown，业务方通常无需使用）；第 3 参数 halfCheckedKeys 为半选节点"
+        },
+        "selectedKeys": {
+            "type": "React.Key[]",
+            "description": "（受控）当前选中的节点 key"
+        },
+        "defaultSelectedKeys": {
+            "type": "React.Key[]",
+            "default": "[]",
+            "description": "默认选中的树节点（非受控初始值）",
+            "_src": "src/Tree/interface.ts:67 defaultSelectedKeys?: Key[]"
+        },
+        "onSelect": {
+            "type": "function",
+            "signature": "(selectedKeys: React.Key[], info: { selected: boolean; selectedNodes: DataNode[]; node: EventDataNode; event: React.SyntheticEvent }) => void",
+            "description": "点击树节点触发"
+        },
+        "expandedKeys": {
+            "type": "React.Key[]",
+            "default": "[]",
+            "description": "（受控）展开指定的树节点；与 defaultExpandedKeys 二选一，受控时 onExpand 需同步更新此值",
+            "_src": "src/Tree/interface.ts:59 expandedKeys?: Key[]"
+        },
+        "defaultExpandedKeys": {
+            "type": "React.Key[]",
+            "default": "[]",
+            "description": "默认展开指定的树节点（非受控初始值）",
+            "_src": "src/Tree/interface.ts:57 defaultExpandedKeys?: Key[]"
+        },
+        "onExpand": {
+            "type": "function",
+            "signature": "(expandedKeys: React.Key[], info: { node: EventDataNode; expanded: boolean; nativeEvent: MouseEvent }) => void",
+            "description": "展开/收起节点时触发；受控模式下需在此回调中同步更新 expandedKeys",
+            "_src": "src/Tree/interface.ts:128 onExpand?"
+        },
+        "defaultExpandAll": {
+            "type": "boolean",
+            "default": false,
+            "description": "默认展开所有树节点。受控模式下与 expandedKeys 同传以 expandedKeys 为准；非受控场景常用于 demo 展示完整层级"
+        },
+        "defaultExpandParent": {
+            "type": "boolean",
+            "default": true,
+            "description": "默认展开父节点",
+            "_src": "src/Tree/interface.ts:55 defaultExpandParent?: boolean"
+        },
+        "autoExpandParent": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否自动展开父节点",
+            "_src": "src/Tree/interface.ts:45 autoExpandParent?: boolean"
+        },
+        "multiple": {
+            "type": "boolean",
+            "default": false,
+            "description": "支持点选多个节点（click 选中行为变为多选）",
+            "_src": "src/Tree/interface.ts:43 multiple?: boolean"
+        },
+        "checkStrictly": {
+            "type": "boolean",
+            "default": false,
+            "description": "checkable 状态下节点选择完全受控（父子节点选中状态不再关联）；开启后 checkedKeys/onCheck 均使用 { checked, halfChecked } 结构",
+            "_src": "src/Tree/interface.ts:47 checkStrictly?: boolean"
+        },
+        "selectable": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否可选中（整棵树级别控制；节点级可在 treeData[].selectable 覆盖）",
+            "_src": "src/Tree/interface.ts:69 selectable?: boolean"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "禁用整棵树（所有节点不可点击/勾选）",
+            "_src": "src/Tree/interface.ts:51 disabled?: boolean"
+        },
+        "blockNode": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否节点占据一行（撑满父容器宽度）",
+            "_src": "src/Tree/interface.ts:89 blockNode?: boolean"
+        },
+        "showIcon": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否展示 TreeNode title 前的图标；设为 true 后需自行定义图标样式",
+            "_src": "src/Tree/interface.ts:81 showIcon?: boolean"
+        },
+        "showLine": {
+            "type": "boolean | { showLeafIcon: boolean }",
+            "default": false,
+            "description": "是否展示连接线"
+        },
+        "icon": {
+            "type": "ReactNode | ((nodeProps: TreeNodeProps) => ReactNode)",
+            "description": "自定义树节点图标；函数形式可按节点 props 动态返回",
+            "_src": "src/Tree/interface.ts:83 icon?: ((nodeProps: TreeNodeProps) => ReactNode) | ReactNode"
+        },
+        "switcherIcon": {
+            "type": "React.ReactElement",
+            "description": "自定义树节点的展开/折叠图标",
+            "_src": "src/Tree/interface.ts:85 switcherIcon?: React.ReactElement<unknown>"
+        },
+        "titleRender": {
+            "type": "function",
+            "signature": "(nodeData: DataNode) => ReactNode",
+            "description": "自定义渲染节点标题内容；组件内部已用 AutoTips 包裹，此回调仅替换内部文本区域",
+            "_src": "src/Tree/Tree.tsx:70 titleRender, / Tree.tsx:171 typeof titleRender === 'function' ? titleRender(nodeData)"
+        },
+        "filterTreeNode": {
+            "type": "function",
+            "signature": "(node: EventDataNode) => boolean",
+            "description": "按需筛选树节点（高亮），返回 true 则该节点高亮",
+            "_src": "src/Tree/interface.ts:71 filterTreeNode?: (node: EventDataNode) => boolean"
+        },
+        "virtual": {
+            "type": "boolean",
+            "default": true,
+            "description": "设置 false 时关闭虚拟滚动（来自 RcTreeProps，通过 ...newProps 透传到 rc-tree）",
+            "_src": "src/Tree/Tree.tsx:725 {...newProps} 透传 RcTreeProps"
+        },
+        "height": {
+            "type": "number",
+            "description": "设置虚拟滚动容器高度（单位 px），设置后内部节点不再支持横向滚动",
+            "_src": "src/Tree/Tree.tsx:725 {...newProps} 透传 RcTreeProps"
+        },
+        "draggable": {
+            "type": "boolean | ((node: DataNode) => boolean)",
+            "default": false,
+            "description": "✅ v5.x 已实施（T2 议题透传到 rc-tree）：传入 draggable={true} 或 (node) => boolean 即生效，rc-tree 渲染拖拽 UI 并触发完整拖拽事件链。协同 prop：配合 onDrop 处理放置逻辑；allowDrop 可控制目标节点是否允许放置"
+        },
+        "allowDrop": {
+            "type": "function",
+            "signature": "({ dropNode: DataNode; dropPosition: number }) => boolean",
+            "description": "是否允许拖拽时放置在该节点（来自 RcTreeProps，通过 ...newProps 透传）；⚠️ 必须配合 draggable={true} 才生效",
+            "_src": "src/Tree/Tree.tsx:101 // T2 议题:draggable + onDragStart/…/allowDrop"
+        },
+        "onDragStart": {
+            "type": "function",
+            "signature": "(info: { event: React.DragEvent; node: EventDataNode }) => void",
+            "description": "开始拖拽时调用（来自 RcTreeProps，通过 ...newProps 透传）",
+            "_src": "src/Tree/Tree.tsx:101 // T2 议题:draggable + onDragStart/…"
+        },
+        "onDragEnter": {
+            "type": "function",
+            "signature": "(info: { event: React.DragEvent; node: EventDataNode; expandedKeys: React.Key[] }) => void",
+            "description": "dragenter 触发时调用（来自 RcTreeProps，通过 ...newProps 透传）",
+            "_src": "src/Tree/Tree.tsx:101 // T2 议题:draggable + …/onDragEnter/…"
+        },
+        "onDragOver": {
+            "type": "function",
+            "signature": "(info: { event: React.DragEvent; node: EventDataNode }) => void",
+            "description": "dragover 触发时调用（来自 RcTreeProps，通过 ...newProps 透传）",
+            "_src": "src/Tree/Tree.tsx:101 // T2 议题:draggable + …/onDragOver/…"
+        },
+        "onDragLeave": {
+            "type": "function",
+            "signature": "(info: { event: React.DragEvent; node: EventDataNode }) => void",
+            "description": "dragleave 触发时调用（来自 RcTreeProps，通过 ...newProps 透传）",
+            "_src": "src/Tree/Tree.tsx:101 // T2 议题:draggable + …/onDragLeave/…"
+        },
+        "onDrop": {
+            "type": "function",
+            "signature": "(info: { event: React.DragEvent; node: EventDataNode; dragNode: EventDataNode; dragNodesKeys: React.Key[]; dropPosition: number; dropToGap: boolean }) => void",
+            "description": "✅ v5.x 已实施（T2 议题）：drop 触发时调用；dropPosition=数字（目标 index）；dropToGap=true 时放在节点间隙（成为兄弟），false 时放入子节点。⚠️ 必须配合 draggable={true}",
+            "_src": "src/Tree/Tree.tsx:101 // T2 议题:draggable + …/onDrop/…"
+        },
+        "onDragEnd": {
+            "type": "function",
+            "signature": "(info: { event: React.DragEvent; node: EventDataNode }) => void",
+            "description": "dragend 触发时调用（来自 RcTreeProps，通过 ...newProps 透传）",
+            "_src": "src/Tree/Tree.tsx:101 // T2 议题:draggable + …/onDragEnd"
+        },
+        "onLoad": {
+            "type": "function",
+            "signature": "(loadedKeys: React.Key[], info: { event: string; node: EventDataNode }) => void",
+            "description": "节点加载完毕时触发（来自 RcTreeProps，通过 ...newProps 透传；配合 loadData 使用）",
+            "_src": "src/Tree/Tree.tsx:725 {...newProps} 透传 RcTreeProps"
+        },
+        "onRightClick": {
+            "type": "function",
+            "signature": "(info: { event: React.MouseEvent; node: EventDataNode }) => void",
+            "description": "响应右键点击（来自 RcTreeProps，通过 ...newProps 透传）",
+            "_src": "src/Tree/Tree.tsx:725 {...newProps} 透传 RcTreeProps"
+        },
+        "loadData": {
+            "type": "function",
+            "signature": "(node: DataNode) => Promise<void>",
+            "description": "节点级懒加载回调；触发条件 = 用户展开 isLeaf=false 且无 children 的节点。⚠️ 与 asyncLoad 互斥：asyncLoad=true 时不要传（走 url 内部 fetch 路径）",
+            "_src": "src/Tree/interface.ts:141 loadData?: (node: DataNode) => Promise<void>"
+        },
+        "loadedKeys": {
+            "type": "React.Key[]",
+            "description": "（受控）已经加载的节点，需要配合 loadData 使用",
+            "_src": "src/Tree/interface.ts:73 loadedKeys?: Key[]"
+        },
+        "showActions": {
+            "type": "boolean | object",
+            "default": false,
+            "description": "是否显示节点内置的操作按钮（add/edit/enable/del/customizeActions）。展示时机 = 节点 hover/mouseenter 触发扇形弹出。⚠️ 协同关系：需要响应按钮点击必须配合 actionsCallback — showActions 控制显示，actionsCallback 处理回调，二者缺一不可"
+        },
+        "actionsCallback": {
+            "type": "function",
+            "signature": "(nodeData: DataNode, type: 'add' | 'edit' | 'enable' | 'del' | string, evt?: React.MouseEvent) => void",
+            "description": "节点内置操作按钮的回调，showActions 开启时有效。⚠️ 与 showActions 是必绑组合，只传 showActions 不传此 prop 则按钮点击无反馈",
+            "_src": "src/Tree/interface.ts:93 actionsCallback?: (nodeData: DataNode, type: ActionType, evt?: React.MouseEvent) => void"
+        },
+        "radioable": {
+            "type": "boolean",
+            "default": false,
+            "description": "节点前添加 Radio 单选框（与 checkable 互斥；开启后内部强制 checkStrictly=true）",
+            "_src": "src/Tree/interface.ts:122 radioable?: boolean"
+        },
+        "showRadio": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否显示 Radio 单选框，radioable 为 true 时有效",
+            "_src": "src/Tree/interface.ts:124 showRadio?: boolean"
+        },
+        "asyncLoad": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否异步加载数据。开启后组件内部 fetch url 接口填充 treeData（必须配合 url prop；⚠️ 与 loadData 互斥：asyncLoad=true 时不要传 loadData）",
+            "_src": "src/Tree/interface.ts:137 asyncLoad?: boolean"
+        },
+        "pagination": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否开启数据分页，asyncLoad 为 true 时有效；分页数据格式 {list, page, size, total}",
+            "_src": "src/Tree/interface.ts:139 pagination?: boolean"
+        },
+        "pageSize": {
+            "type": "{ page?: number; size?: number }",
+            "default": "{ page: 1, size: 10 }",
+            "description": "分页参数，pagination 为 true 时有效",
+            "_src": "src/Tree/interface.ts:143 pageSize?: { page?: number; size?: number }"
+        },
+        "replaceFields": {
+            "type": "object",
+            "default": "{ key: 'key', parentId: 'parentId', children: 'children', title: 'title', loadKey: 'key' }",
+            "description": "自定义节点 title/key/children/parentId/loadKey 的字段名（用于后端数据字段与组件期望字段的映射）",
+            "_src": "src/Tree/interface.ts:109-121 replaceFields?"
+        },
+        "localFilter": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否开启本地数据过滤（开启后配合 localParams 或 onFilter 实现前端搜索）",
+            "_src": "src/Tree/interface.ts:145 localFilter?: boolean"
+        },
+        "localParams": {
+            "type": "{ searchKey: string; searchValue: string }",
+            "description": "本地数据过滤参数，localFilter 为 true 时有效；searchKey 为过滤字段名，searchValue 为过滤值",
+            "_src": "src/Tree/interface.ts:147-152 localParams?"
+        },
+        "onFilter": {
+            "type": "function",
+            "signature": "(data: DataNode[]) => DataNode[]",
+            "description": "本地数据过滤回调，localFilter 为 true 时有效；优先级高于 localParams 内置过滤逻辑",
+            "_src": "src/Tree/interface.ts:154 onFilter?: (data: DataNode[]) => DataNode[]"
+        },
+        "loadMoreNode": {
+            "type": "ReactNode",
+            "description": "自定义加载更多节点内容，asyncLoad 为 true 且 pagination 为 true 时有效",
+            "_src": "src/Tree/interface.ts:156 loadMoreNode?: ReactNode"
+        },
+        "ctx": {
+            "type": "string",
+            "description": "请求上下文（传给 snack-kit Request）",
+            "_src": "src/Tree/interface.ts:97 ctx?: string"
+        },
+        "method": {
+            "type": "enum",
+            "values": ["GET", "POST", "Get", "Post", "get", "post"],
+            "default": "GET",
+            "description": "请求方法",
+            "_src": "src/Tree/interface.ts:103 method?: 'GET' | 'POST' | ..."
+        },
+        "headers": {
+            "type": "object",
+            "description": "请求头（类型为 RequestConfig['headers']）",
+            "_src": "src/Tree/interface.ts:99 headers?: RequestConfig['headers']"
+        },
+        "params": {
+            "type": "Object | null",
+            "description": "请求参数（GET 时作为 query，POST 时作为 body）",
+            "_src": "src/Tree/interface.ts:101 params?: Object | null"
+        },
+        "requestCallback": {
+            "type": "function",
+            "signature": "(treeData: unknown) => unknown",
+            "description": "请求成功后的数据预处理回调（返回值将替换原始响应作为树数据）",
+            "_src": "src/Tree/interface.ts:105 requestCallback?: (treeData: unknown) => unknown"
+        },
+        "paramsCallback": {
+            "type": "function",
+            "signature": "(params: { [name: string]: unknown }) => unknown",
+            "description": "请求发送前的参数处理回调（可动态修改/扩展请求参数）",
+            "_src": "src/Tree/interface.ts:158 paramsCallback?: (params: ...) => unknown"
+        },
+        "refresh": {
+            "type": "number",
+            "description": "刷新组件（变更此值触发重新请求数据，常配合 url+asyncLoad 使用）",
+            "_src": "src/Tree/interface.ts:107 refresh?: number"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "树容器内联样式",
+            "_src": "src/Tree/interface.ts:79 style?: React.CSSProperties"
+        },
+        "wrapperClassName": {
+            "type": "string",
+            "description": "包裹容器的 className（对应最外层 div.paraui-v4-tree-wrapper）",
+            "_src": "src/Tree/interface.ts:166 wrapperClassName?: string"
+        },
+        "wrapperStyle": {
+            "type": "React.CSSProperties",
+            "description": "包裹容器的内联样式",
+            "_src": "src/Tree/interface.ts:168 wrapperStyle?: React.CSSProperties"
+        },
+        "showLoading": {
+            "type": "boolean",
+            "default": true,
+            "description": "接口请求时是否显示 loading 状态（默认开启，关闭后请求期间无 loading 遮罩）",
+            "_src": "src/Tree/interface.ts:170 showLoading?: boolean"
+        },
+        "loadingNode": {
+            "type": "ReactNode",
+            "description": "自定义 loading 节点内容（替换默认 Loading 组件）",
+            "_src": "src/Tree/interface.ts:172 loadingNode?: ReactNode"
+        },
+        "emptyClassName": {
+            "type": "string",
+            "description": "空状态容器 className",
+            "_src": "src/Tree/interface.ts:160 emptyClassName?: string"
+        },
+        "emptyProps": {
+            "type": "EmptyProps",
+            "description": "空状态 Empty 组件 props（可自定义图片/文案等）",
+            "_src": "src/Tree/interface.ts:162 emptyProps?: EmptyProps"
+        },
+        "notFoundContent": {
+            "type": "ReactNode",
+            "description": "自定义空数据节点（优先级高于 emptyProps）",
+            "_src": "src/Tree/interface.ts:164 notFoundContent?: ReactNode"
+        },
+        "tipMaxWidth": {
+            "type": "number | string",
+            "default": 500,
+            "description": "AutoTips 节点 title 超长提示的最大宽度",
+            "_src": "src/Tree/interface.ts:174 tipMaxWidth?: number | string"
+        }
+    },
+    "do": [
+        "对于大数据量层级，优先使用异步加载 (asyncLoad) 或 url 配置",
+        "保持 key 在整个树范围内的唯一性",
+        "受控展开/勾选时（expandedKeys/checkedKeys），务必在 onExpand/onCheck 中同步更新对应 state",
+        "showActions 与 actionsCallback 必须成对使用，缺少 actionsCallback 会导致按钮点击无反馈",
+        "拖拽场景：draggable + onDrop 成对传入，allowDrop 按需控制目标节点"
+    ],
+    "dont": [
+        "在 render 中从头构造复杂的 treeData 导致不必要的重渲染",
+        "同时使用 url 和 treeData（应明确数据来源）",
+        "asyncLoad=true 时同时传 loadData（二者互斥）",
+        "checkedKeys/expandedKeys 受控时忘记绑定 onCheck/onExpand 更新 state（会导致 UI 无响应）",
+        "rc-* 库 strict 模式校验失败是已知边缘情况，不要为过 strict 删除真实的 prop"
+    ],
+    "events": {
+        "onCheck": {
+            "signature": "(checkedKeys: React.Key[], info: unknown, halfCheckedKeys?: React.Key[]) => void",
+            "asyncSupported": false,
+            "examples": [
+                "多选 checkable 模式：onCheck={(keys) => setCheckedKeys(keys as string[])}",
+                "checkStrictly=true 时 checkedKeys 是已选 key 数组（父子不联动）；回调第三参 halfCheckedKeys 为半选节点",
+                "radioable=true 单选模式：onCheck={(keys) => setSingleKey(keys[0] as string)}"
+            ],
+            "commonMistakes": [
+                "假设 checkedKeys 在 checkStrictly=false 时包含半选节点——半选节点在第三参 halfCheckedKeys，第一参只有完全选中的",
+                "把 info 参数用于业务逻辑——info 类型是 unknown，内部实现细节，不保证稳定",
+                "radioable=true 时 onCheck 签名相同但 checkedKeys 最多只有一个元素（单选）"
+            ]
+        },
+        "onExpand": {
+            "signature": "(expandedKeys: React.Key[], info: { node: EventDataNode; expanded: boolean; nativeEvent: MouseEvent }) => void",
+            "asyncSupported": false,
+            "examples": [
+                "受控展开：onExpand={(keys) => setExpandedKeys(keys as string[])}",
+                "展开特定节点后加载数据：onExpand={(keys, {node}) => fetchNodeData(node.key)}",
+                "折叠时记录状态：onExpand={(keys, {expanded}) => !expanded && logCollapse()}"
+            ],
+            "commonMistakes": [
+                "受控模式（传了 expandedKeys）但没在 onExpand 中更新 state——导致点击展开/折叠无响应",
+                "在 onExpand 中直接 mutate expandedKeys 数组——必须传新数组引用触发 re-render"
+            ]
+        },
+        "onSelect": {
+            "signature": "(selectedKeys: React.Key[], info: { selected: boolean; selectedNodes: DataNode[]; node: EventDataNode; event: React.SyntheticEvent }) => void",
+            "asyncSupported": false,
+            "examples": [
+                "单选节点（默认）：onSelect={(keys) => setSel(keys[0] as string)}",
+                "multiple=true 多选：onSelect={(keys) => setSelectedKeys(keys as string[])}",
+                "点击同一节点再次取消：info.selected=false 时表示当前节点被取消选中"
+            ],
+            "commonMistakes": [
+                "假设 onSelect 在 checkable=true 时也触发——checkbox 点击触发 onCheck，节点点击触发 onSelect，二者独立",
+                "radioable=true 场景下 onSelect 不触发——radioable 使用 onCheck 路径"
+            ]
+        },
+        "actionsCallback": {
+            "signature": "(nodeData: DataNode, type: 'add' | 'edit' | 'enable' | 'del' | string, evt?: React.MouseEvent) => void",
+            "asyncSupported": false,
+            "examples": [
+                "通用 switch 处理：actionsCallback={(node, type) => { if(type==='del') confirmDel(node.key); }}",
+                "自定义 action：showActions={{ customizeActions: [{action:'export', text:'导出', icon:<ExportIcon/>}] }}，actionsCallback 收到 type='export'",
+                "配合权限控制显隐：showActions={{ add: {text:'新增', show:(node)=>node.level<3} }}"
+            ],
+            "commonMistakes": [
+                "只传 showActions 不传 actionsCallback——按钮点击无任何回调，用户操作被静默忽略",
+                "假设 type 只有 'add'/'edit'/'enable'/'del'——customizeActions 中 action 字段也会作为 type 传入"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "checkedKeys 受控时 checkStrictly=false 应传 Key[]，checkStrictly=true 应传 { checked: Key[]; halfChecked: Key[] }",
+            "wrong": "// checkStrictly=true 但传数组\ncheckedKeys={selectedKeys}  // 类型不匹配",
+            "right": "// checkStrictly=true\ncheckedKeys={{ checked: selectedKeys, halfChecked: halfKeys }}"
+        },
+        {
+            "issue": "onCheck 第一参类型随 checkStrictly 变化，需正确处理两种形式",
+            "wrong": "onCheck={(keys) => setKeys(keys as Key[])}  // checkStrictly=true 时 keys 是 {checked,halfChecked} 对象",
+            "right": "onCheck={(keys) => setKeys(Array.isArray(keys) ? keys : keys.checked)}"
+        },
+        {
+            "issue": "rc-* 库继承的 prop（RcTreeProps）在 strict 校验可能报告额外 prop，属已知边缘情况",
+            "wrong": "// 假设 strict 失败说明 metadata 有误——Tree 的 rc-* 继承是已知例外",
+            "right": "// strict 失败是可接受的已知情况；确认 interface.ts 有 prop 即可，不要删除真实 prop"
+        },
+        {
+            "issue": "DataNode 类型 key 是 React.Key（string | number），不是 string",
+            "wrong": "const key: string = node.key  // TS 报错：Type 'Key' is not assignable to type 'string'",
+            "right": "const key: React.Key = node.key  // 或 String(node.key) 转字符串"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Tree",
+        "adapter": null
+    }
+}

package/lib/Tree/interface.d.ts

@@ -2,7 +2,7 @@ import { default as React, ReactNode } from 'react';
 import { TreeProps as RcTreeProps } from 'rc-tree';
 import { DataNode, EventDataNode, Key } from 'rc-tree/lib/interface';
 import { EmptyProps } from '../Empty';
-import { ParaRequestConfig as RequestConfig } from '@paraview/lib/http/interface';
+import { ParaRequestConfig as RequestConfig } from '../Utils/snack-kit-shims';
 export type HasAction = (nodeData: DataNode) => boolean;
 export type ActionItem = boolean | {
     text: string;