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

package/es/Tooltip/component.json

@@ -0,0 +1,176 @@
+{
+    "name": "Tooltip",
+    "category": "Data Display",
+    "description": "简单的文字提示气泡框",
+    "semantic": {
+        "intent": [
+            "辅助说明",
+            "信息补充",
+            "操作提示"
+        ],
+        "useCases": [
+            "按钮解释",
+            "被截断文本显示",
+            "图标含义说明"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "visible",
+        "hidden"
+    ],
+    "idealProps": {
+        "title": {
+            "type": "string | ReactNode",
+            "description": "提示文字"
+        },
+        "placement": {
+            "type": "enum",
+            "values": [
+                "top",
+                "left",
+                "right",
+                "bottom",
+                "topLeft",
+                "topRight",
+                "bottomLeft",
+                "bottomRight",
+                "leftTop",
+                "leftBottom",
+                "rightTop",
+                "rightBottom"
+            ],
+            "default": "topLeft",
+            "description": "气泡框位置。配合 `autoAdjustOverflow=true` 可被遮挡时自动翻转。**长 content + maxWidth 较大时优先 top/bottom 减少水平空间冲突**"
+        },
+        "maxWidth": {
+            "type": "string | number",
+            "default": 500,
+            "description": "气泡最大宽度。`number` = px;`string` = 任意合法 CSS 长度(`'200px'` / `'20rem'`)。默认 500px 适合大多数长 title 场景。R23 TT3 docs 协同补强"
+        },
+        "trigger": {
+            "type": "enum",
+            "values": [
+                "hover",
+                "focus",
+                "click",
+                "contextMenu"
+            ],
+            "default": "hover",
+            "description": "触发行为。**`trigger=[]` 受控屏蔽写法已 deprecated(R23 TT2)**——请改用 `visible={false}`。老写法仍可用但 dev 环境 console.warn 一次提示迁移;v6 可能收紧类型不接受空数组,提前迁移"
+        },
+        "visible": {
+            "type": "boolean",
+            "default": "undefined",
+            "description": "**控制浮层显示(受控,src 真实主名)**。**三路语义**(R24 W-2 文档化):`true`=强制显示气泡;`false`=强制隐藏(推荐替代 deprecated `trigger=[]`);`undefined` 或不传=fallback 到 `open`,再 fallback 到 trigger 默认触发逻辑(`visible ?? open ?? trigger 自动`,src/Tooltip/index.tsx:27)。条件受控:`visible={isDisabled ? false : undefined}`"
+        },
+        "open": {
+            "type": "boolean",
+            "default": "undefined",
+            "description": "`visible` 的别名(来自 antd 风格);与 visible 二选一,不要同时传"
+        },
+        "onVisibleChange": {
+            "type": "function",
+            "signature": "(visible: boolean) => void",
+            "description": "**显示隐藏回调(src 真实事件名,非 onOpenChange)**。受控用法配合 visible/open 使用;受控 visible 时 hover/click 仍触发本回调但 Tooltip 不会自更新——必须父组件 setState。**受控 trigger 选择建议**(R24 W-2 R23 TT2 round 标注):新手引导等场景若不希望 hover 持续触发本回调改变 step,建议 `trigger='click'`;**不要用 deprecated `trigger=[]`**(R23 TT2)"
+        },
+        "defaultVisible": {
+            "type": "boolean",
+            "default": false,
+            "description": "初始是否显示气泡（非受控初始值，src/Tooltip/index.tsx:18,193 实证：`useState(props.defaultVisible!)` 作为初始 visible 状态；默认 false。传了 visible/open 受控 prop 后 defaultVisible 被覆盖）"
+        },
+        "mouseEnterDelay": {
+            "type": "number",
+            "default": 0.1,
+            "description": "鼠标移入后延迟显示的时间（单位：秒，src/Tooltip/index.tsx:190 defaultProps 实证：默认 0.1s）。⚠️ **单位是秒不是毫秒**（0.1 = 100ms）"
+        },
+        "mouseLeaveDelay": {
+            "type": "number",
+            "default": 0.1,
+            "description": "鼠标移出后延迟隐藏的时间（单位：秒，src/Tooltip/index.tsx:191 defaultProps 实证：默认 0.1s）。⚠️ **单位是秒不是毫秒**"
+        },
+        "autoAdjustOverflow": {
+            "type": "boolean",
+            "default": true,
+            "description": "气泡被遮挡时是否自动翻转位置（src/Tooltip/index.tsx:64-65,192 实证：默认 true，传入 getPlacements 生成弹出方向配置）"
+        },
+        "followCursor": {
+            "type": "boolean",
+            "default": false,
+            "description": "气泡是否跟随鼠标光标移动（src/Tooltip/index.tsx:122,171-178,194 实证：true 时强制 placement='top' 并在外层 div 监听 mousemove 动态更新 targetOffset；与精确 placement 互斥）"
+        },
+        "overlayClassName": {
+            "type": "string",
+            "description": "气泡浮层的自定义类名（src/Tooltip/index.tsx:115,135 实证：与内置 paraui-tooltip 类合并透传到 RcTooltip overlayClassName）"
+        },
+        "overlayInnerStyle": {
+            "type": "React.CSSProperties",
+            "description": "气泡内容区内联样式（src/Tooltip/index.tsx:116,164 实证：透传到 RcTooltip overlayInnerStyle，作用于内容容器而非浮层外壳）"
+        },
+        "overlayStyle": {
+            "type": "React.CSSProperties",
+            "description": "气泡浮层外壳内联样式（src/Tooltip/index.tsx:117,138-140 实证：与 maxWidth 合并后透传到 RcTooltip overlayStyle）"
+        }
+    },
+    "do": [
+        "提示内容应当精简，避免超过两行文字",
+        "用于解释图标或被截断的文本（配合 AutoTips 使用效果更佳）",
+        "受控场景用 `visible={false}` 替代已废弃的 `trigger=[]` 写法——v6 可能移除空数组支持（src/Tooltip/index.tsx:29-40 dev warn 实证）",
+        "Modal/Dialog 内的 Tooltip 建议传 getPopupContainer 指向 modal 容器，避免 overflow:hidden 截断浮层",
+        "需要叠加禁用视觉图标时用 showForbidIcon={true}（新名）而非 disabled（deprecated），两者源码同路径：`(disabled || showForbidIcon) && <Forbid />`"
+    ],
+    "dont": [
+        "在 Tooltip 中放入复杂交互内容（应使用 Popover）",
+        "提示内容为空——title 为空时 Tooltip 强制不显示（src/Tooltip/index.tsx:42-45 isUntitled 判断）",
+        "不要把 `disabled` 理解为『禁用气泡显示』——src 实现是叠加红色 Forbid 图标，与 antd/mui 同名 prop 含义相反；用 `visible={false}` 来强制隐藏气泡",
+        "不要同时传 visible 和 open——两者是同义别名，优先取 visible，同时传会造成语义混淆（src:27 `props.visible ?? props.open` 实证）",
+        "不要给 mouseEnterDelay / mouseLeaveDelay 传毫秒值（如 100）——单位是秒，传 100 = 100秒延迟"
+    ],
+    "events": {
+        "onVisibleChange": {
+            "signature": "(visible: boolean) => void",
+            "asyncSupported": false,
+            "examples": [
+                "非受控模式下跟踪气泡显示状态：onVisibleChange={(v) => setIsHovered(v)}",
+                "受控模式配合 useState：onVisibleChange={(v) => setVisible(v)}",
+                "新手引导场景：`trigger='click'` + onVisibleChange 控制引导步骤切换（避免 hover 持续触发）"
+            ],
+            "commonMistakes": [
+                "回调名写成 onOpenChange → src 真实回调名是 onVisibleChange，写错无效（RcTooltip 接口名），不会有 TS 报错但回调不触发",
+                "受控模式（visible=xxx）下期望 onVisibleChange 触发后气泡自动更新 → 受控时内部 state 不更新，必须父组件在 onVisibleChange 里 setState",
+                "假设 onVisibleChange 在 title 为空时也会触发 → src:46-50 isUntitled()=true 时 onVisibleChange 不被调用"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "disabled 的语义与 antd/mui 相反——不是禁用气泡而是叠加禁用图标",
+            "wrong": "<Tooltip disabled={isLoading} title='提示'>  // 期望 isLoading 时不显示气泡 → 实际只是叠加红色图标，气泡照常显示",
+            "right": "<Tooltip visible={isLoading ? false : undefined} title='提示'>  // 正确：visible=false 才能强制隐藏气泡"
+        },
+        {
+            "issue": "mouseEnterDelay / mouseLeaveDelay 单位是秒不是毫秒",
+            "wrong": "<Tooltip mouseEnterDelay={500} />  // 500 秒 = 8 分钟才显示",
+            "right": "<Tooltip mouseEnterDelay={0.5} />  // 0.5 秒 = 500ms"
+        },
+        {
+            "issue": "followCursor={true} 时 placement 被强制覆盖为 'top'，设置其他 placement 无效",
+            "wrong": "<Tooltip followCursor={true} placement='bottomRight' />  // placement 被 src:128 强制改为 'top'",
+            "right": "<Tooltip followCursor={true} />  // followCursor 场景只支持 top，无需传 placement"
+        },
+        {
+            "issue": "TooltipProps 继承自 rc-tooltip，overlayStyle 和 overlayInnerStyle 作用 DOM 层级不同",
+            "wrong": "overlayStyle={{ color: 'red' }}  // overlayStyle 作用于浮层外壳，文字颜色无效",
+            "right": "overlayInnerStyle={{ color: 'red' }}  // overlayInnerStyle 作用于内容容器，文字颜色生效"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Tooltip",
+        "adapter": null
+    }
+}

package/es/Tooltip/index.js

@@ -1,101 +1,106 @@
-import { j as f } from "../_virtual/jsx-runtime.js";
+import { j as r } from "../_virtual/jsx-runtime.js";
 import l from "react";
-import _ from "rc-tooltip";
-import k, { getDisabledCompatibleChildren as C, mapLegacyPlacement as z } from "./utils.js";
-import I from "clsx";
-import { $rcPrefixCls as O, $prefixCls as U } from "../GlobalContext/constant.js";
-import { Forbid as q } from "../node_modules/@para-ui/icons/Forbid/index.js";
+import k from "rc-tooltip";
+import z, { getDisabledCompatibleChildren as O, mapLegacyPlacement as U } from "./utils.js";
+import q from "clsx";
+import { $rcPrefixCls as R, $prefixCls as G } from "../GlobalContext/constant.js";
+import { Forbid as J } from "../node_modules/@para-ui/icons/Forbid/index.js";
 import './index.css';/* empty css           */
-const R = l.forwardRef((e, w) => {
-  const [P, u] = l.useState(e.defaultVisible), c = l.useRef(null), d = l.useRef(null), [$, j] = l.useState([0, 0]);
+const w = l.forwardRef((e, P) => {
+  const [$, u] = l.useState(e.defaultVisible), c = l.useRef(null), d = l.useRef(null), [j, T] = l.useState([0, 0]), g = l.useRef(!1);
   l.useEffect(() => {
     ("visible" in e || "open" in e) && u(!!(e.visible ?? e.open));
-  }, [e.visible ?? e.open]);
+  }, [e.visible ?? e.open]), l.useEffect(() => {
+    process.env.NODE_ENV !== "production" && !g.current && Array.isArray(e.trigger) && e.trigger.length === 0 && (g.current = !0, console.warn(
+      "[Tooltip] `trigger=[]` 受控屏蔽写法已 deprecated,请改用 `visible={false}`(语义更清晰);v6 可能收紧 trigger 类型,提前迁移。"
+    ));
+  }, [e.trigger]);
   const m = () => {
     const { title: t } = e;
     return !t && t !== 0;
-  }, T = (t) => {
+  }, E = (t) => {
     "visible" in e || "open" in e || u(m() ? !1 : t), m() || e.onVisibleChange?.(t);
   }, p = () => {
     const { builtinPlacements: t, autoAdjustOverflow: i } = e;
-    return t || k({ autoAdjustOverflow: i });
+    return t || z({ autoAdjustOverflow: i });
   }, S = (t, i) => {
     const s = p(), o = Object.keys(s).find(
       (a) => s[a].points[0] === i.points[0] && s[a].points[1] === i.points[1]
     );
     if (!o)
       return;
-    const r = t.getBoundingClientRect(), n = {
+    const f = t.getBoundingClientRect(), n = {
       top: "50%",
       left: "50%"
     };
-    o.indexOf("top") >= 0 || o.indexOf("Bottom") >= 0 ? n.top = `${r.height - (i.offset?.[1] || 0)}px` : (o.indexOf("Top") >= 0 || o.indexOf("bottom") >= 0) && (n.top = `${-(i.offset?.[1] || 0)}px`), o.indexOf("left") >= 0 || o.indexOf("Right") >= 0 ? n.left = `${r.width - (i.offset?.[0] || 0)}px` : (o.indexOf("right") >= 0 || o.indexOf("Left") >= 0) && (n.left = `${-(i.offset?.[0] || 0)}px`), t.style.transformOrigin = `${n.left} ${n.top}`;
+    o.indexOf("top") >= 0 || o.indexOf("Bottom") >= 0 ? n.top = `${f.height - (i.offset?.[1] || 0)}px` : (o.indexOf("Top") >= 0 || o.indexOf("bottom") >= 0) && (n.top = `${-(i.offset?.[1] || 0)}px`), o.indexOf("left") >= 0 || o.indexOf("Right") >= 0 ? n.left = `${f.width - (i.offset?.[0] || 0)}px` : (o.indexOf("right") >= 0 || o.indexOf("Left") >= 0) && (n.left = `${-(i.offset?.[0] || 0)}px`), t.style.transformOrigin = `${n.left} ${n.top}`;
   }, V = (t) => {
     if (c.current) {
-      const i = d.current?.popupRef?.current?.getElement()?.offsetHeight || 0, s = i === 0 ? 60 : 30, { x: o, y: r, width: n } = c.current.getBoundingClientRect(), a = t.clientX - (o + n / 2), Y = t.clientY - r + i + s;
+      const i = d.current?.popupRef?.current?.getElement()?.offsetHeight || 0, s = i === 0 ? 60 : 30, { x: o, y: f, width: n } = c.current.getBoundingClientRect(), a = t.clientX - (o + n / 2), Y = t.clientY - f + i + s;
       setTimeout(() => {
-        j([-a, -Y]);
+        T([-a, -Y]);
       });
     }
   }, {
-    prefixCls: D = `${O}-tooltip`,
-    getPopupContainer: E,
-    overlayClassName: L,
-    overlayInnerStyle: M,
-    overlayStyle: N,
+    prefixCls: N = `${R}-tooltip`,
+    getPopupContainer: A,
+    overlayClassName: D,
+    overlayInnerStyle: L,
+    overlayStyle: M,
     children: x,
-    title: A,
+    title: W,
     placement: B,
-    isPopover: W,
+    isPopover: F,
     followCursor: b,
-    maxWidth: g,
-    disabled: F,
-    ...H
+    maxWidth: v,
+    disabled: _,
+    showForbidIcon: H,
+    ...I
   } = e;
-  let v = P;
-  !("visible" in e || "open" in e) && m() && (v = !1);
-  const X = I(!W && `${U}-tooltip`, L), y = { ...N };
-  g && (y.maxWidth = g);
-  const h = { targetOffset: $ };
-  return e.offset && (h.offset = e.offset), /* @__PURE__ */ f.jsx(
-    _,
+  let y = $;
+  !("visible" in e || "open" in e) && m() && (y = !1);
+  const X = q(!F && `${G}-tooltip`, D), h = { ...M };
+  v && (h.maxWidth = v);
+  const C = { targetOffset: j };
+  return e.offset && (C.offset = e.offset), /* @__PURE__ */ r.jsx(
+    k,
     {
-      ...H,
-      prefixCls: D,
-      placement: b ? "top" : z(B),
+      ...I,
+      prefixCls: N,
+      placement: b ? "top" : U(B),
       overlayClassName: X,
-      getTooltipContainer: E,
-      ref: w || d,
+      getTooltipContainer: A,
+      ref: P || d,
       builtinPlacements: p(),
-      overlay: /* @__PURE__ */ f.jsxs(f.Fragment, { children: [
-        F && /* @__PURE__ */ f.jsx(q, { className: "disabled-svg" }),
-        A
+      overlay: /* @__PURE__ */ r.jsxs(r.Fragment, { children: [
+        (_ || H) && /* @__PURE__ */ r.jsx(J, { className: "disabled-svg" }),
+        W
       ] }),
-      visible: v,
-      align: h,
-      onVisibleChange: T,
+      visible: y,
+      align: C,
+      onVisibleChange: E,
       onPopupAlign: S,
-      overlayStyle: y,
-      overlayInnerStyle: M,
+      overlayStyle: h,
+      overlayInnerStyle: L,
       arrowContent: null,
       motion: {
-        motionName: `${O}-tooltip-zoom-big-fast`,
+        motionName: `${R}-tooltip-zoom-big-fast`,
         motionDeadline: 1e3
       },
-      children: b ? /* @__PURE__ */ f.jsx(
+      children: b ? /* @__PURE__ */ r.jsx(
         "div",
         {
           style: { display: "inline-block" },
           ref: c,
           onMouseMove: V,
-          children: C(x)
+          children: O(x)
         }
-      ) : C(x)
+      ) : O(x)
     }
   );
 });
-R.displayName = "Tooltip";
-R.defaultProps = {
+w.displayName = "Tooltip";
+w.defaultProps = {
   placement: "topLeft",
   mouseEnterDelay: 0.1,
   mouseLeaveDelay: 0.1,
@@ -105,7 +110,7 @@ R.defaultProps = {
   maxWidth: 500
 };
 export {
-  R as Tooltip,
-  R as default
+  w as Tooltip,
+  w as default
 };
 //# sourceMappingURL=index.js.map

package/es/Tooltip/interface.d.ts

@@ -14,12 +14,25 @@ export interface TooltipProps extends Partial<Omit<RcTooltipProps, 'children'>>
     children?: React.ReactNode;
     /** 控制浮层是否显示 */
     open?: boolean;
+    /**
+     * 受控屏蔽气泡显示(推荐替代 `trigger=[]` 受控隐藏写法)。
+     * - `visible !== undefined` → 完全受控,显隐由 visible 控制(覆盖 trigger hover/click 默认行为)
+     * - `visible === undefined`(默认)→ 走 trigger 触发(原行为不变)
+     * 与 `open` 同义,优先级:`visible ?? open`(src/Tooltip/index.tsx)。@since v5.x.next
+     */
+    visible?: boolean;
     /** 跟随光标移动 */
     followCursor?: boolean;
     /** 容器最大宽度 */
     maxWidth?: number | string;
-    /** 禁用标志 */
+    /**
+     * @deprecated v5.x.next 改用 `showForbidIcon`(自描述命名,业界对齐);v6 移除。
+     * 语义不变:在 trigger 旁叠加红色 Forbid SVG 图标(不影响气泡显示)。
+     * 详见 BREAKING-CHANGES §B5。
+     */
     disabled?: boolean;
+    /** 在 trigger 节点旁叠加红色 Forbid 禁用 SVG 图标(原 `disabled` 重命名,自描述命名)。不影响气泡显示行为(气泡仍走 title/visible/trigger 控制)。@since v5.x.next */
+    showForbidIcon?: boolean;
     /** 偏移 */
     offset?: [number, number];
     [name: string]: unknown;

package/es/Tooltip/utils.js

@@ -16,7 +16,7 @@ function b(t) {
     ...t
   };
 }
-function E(t) {
+function L(t) {
   const { horizontalArrowShift: o = 16, verticalArrowShift: s = 8, autoAdjustOverflow: f } = t, e = {
     left: {
       points: ["cr", "cl"],
@@ -81,10 +81,10 @@ const u = (t, o) => {
     t && e in t && (s[e] = t[e], delete f[e]);
   }), { picked: s, omitted: f };
 };
-function L(t) {
+function v(t) {
   const o = i.isValidElement(t) ? t : /* @__PURE__ */ r.jsx("span", { children: t });
-  if (o.type === "button" && o.props.disabled) {
-    const { picked: s, omitted: f } = u(o.props.style, [
+  if (o.props && o.props.disabled === !0) {
+    const { picked: s, omitted: f } = u(o.props.style || {}, [
       "position",
       "left",
       "right",
@@ -170,8 +170,8 @@ function h(t) {
   }[o];
 }
 export {
-  E as default,
-  L as getDisabledCompatibleChildren,
+  L as default,
+  v as getDisabledCompatibleChildren,
   g as mapLegacyPlacement
 };
 //# sourceMappingURL=utils.js.map

package/es/Transfer/component.json

@@ -0,0 +1,157 @@
+{
+    "name": "Transfer",
+    "category": "Data Entry",
+    "description": "穿梭框,双栏穿梭选择框",
+    "semantic": {
+        "intent": [
+            "多项选择",
+            "数据移动",
+            "分类归纳"
+        ],
+        "useCases": [
+            "权限配置",
+            "角色分配",
+            "字段筛选"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "标准穿梭框(多选 + 内置搜索)"
+        }
+    },
+    "states": [
+        "default",
+        "disabled"
+    ],
+    "idealProps": {
+        "data": {
+            "type": "Array<ItemDataProps>",
+            "default": "[]",
+            "itemSchema": {
+                "key": { "type": "string", "description": "唯一标识（与 value[] 对比；改字段名时用 customKey）" },
+                "name": { "type": "string", "description": "显示名" },
+                "description": { "type": "string", "description": "描述文字" },
+                "checked": { "type": "boolean", "description": "是否已勾选" },
+                "disabled": { "type": "boolean", "description": "是否禁用" },
+                "hide": { "type": "boolean", "description": "是否隐藏" },
+                "tagColor": { "type": "string", "description": "tag 色" }
+            },
+            "description": "数据源(**真实 prop 名是 data 不是 dataSource**);**对外导出类型名是 IItemDataProps**(有 I 前缀,src/index.ts 重命名导出),业务侧 import 用 `import { IItemDataProps } from '@para-ui/core/Transfer'`;ItemDataProps = { key?: string; name?: string; description?: string; checked?: boolean; disabled?: boolean; hide?: boolean; tagColor?: string; [k: string]: unknown };src/Transfer/box.tsx:49。**业务 any[] 数据**:若字段名不是 key/name(例如 id/label),建议父层 map 适配成 IItemDataProps 形状,或用 customKey 让 value 比对换字段"
+        },
+        "value": {
+            "type": "Array<string>",
+            "default": "[]",
+            "description": "右侧框已选中的 key 集合(**真实 prop 名是 value 不是 targetKeys**);受控数组,组件内部按 customKey 比对 data 分流到左右两侧;src/Transfer/index.tsx:236 useEffect 监听 value/data 同步"
+        },
+        "onChange": {
+            "type": "(keys: Array<string>) => void",
+            "description": "右侧 key 集合变化回调(穿梭 / 排序 / 上下移动都会触发);**回参是 key 数组不是 item 对象数组**;src/Transfer/index.tsx:150"
+        },
+        "onSort": {
+            "type": "(keys: Array<string>) => void",
+            "description": "右侧拖拽排序 / 上下移动后回调;触发时机:rightData splice 之后;src/Transfer/index.tsx:170 / 190 / 230;onChange 在 onSort 之前也会触发一次(同步右侧 key 序列)"
+        },
+        "customKey": {
+            "type": "string",
+            "default": "key",
+            "description": "自定义唯一键字段名;改这个会让 value 比对 data[customKey] 而非 data.key — 适用于业务数据自带 id/code 不想 rename 为 key 的场景"
+        },
+        "titles": {
+            "type": "Array<string>",
+            "default": "['左侧', '右侧']",
+            "description": "[左侧标题, 右侧标题];默认值来自 i18n localeJson(zh: '左侧'/'右侧',en: 'Left'/'Right');传两元数组覆盖"
+        },
+        "multiple": {
+            "type": "boolean",
+            "default": "true",
+            "description": "是否多选;false 时每侧 checkbox 单选语义,选中新项自动清空旧选"
+        },
+        "trim": {
+            "type": "boolean",
+            "default": "false",
+            "description": "搜索时是否去除首尾空格(toUpperCase 大小写不敏感是固定行为,trim 只控空格)"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": "false",
+            "description": "整体禁用(组件层);若只想禁某条 item,用 ItemDataProps.disabled — 二者独立可叠加"
+        },
+        "render": {
+            "type": "(item: ItemDataProps) => void",
+            "description": "对每条 item 的预处理 hook(在 useEffect 分流前调用,可改 item 字段);**注意是副作用函数(返回 void),不是返回 ReactNode 的 render prop** — 与 rightIcon 易混(rightIcon 才是返回 ReactNode);src/Transfer/index.tsx:242"
+        },
+        "rightIcon": {
+            "type": "(item: ItemDataProps) => ReactNode",
+            "description": "每行右侧自定义渲染(放 Help 图标 / Popover 等);返回 ReactNode,与 render 副作用 hook 不同"
+        }
+    },
+    "do": [
+        "在源数据量大且需要多选时使用 Transfer",
+        "提供清晰的 List Title",
+        "value 始终保持 string[] 类型(组件内部按 customKey 比对)"
+    ],
+    "dont": [
+        "在移动端使用 Transfer(交互困难)",
+        "数据量极小(<5)时使用 Transfer(推荐 Checkbox Group)",
+        "把 dataSource / targetKeys 当 prop 名(那是 Ant Design 命名,本组件实际是 data / value)",
+        "期待 onSelectChange / onCheck 回调(本组件无 checkbox 勾选未穿梭的回调 — onChange 仅在穿梭/排序/移动完成后触发;若需追踪'选中变化'只能在 onChange 后由 left/right key 集合推导)",
+        "期待 size / compact / dense prop(本组件不支持紧凑模式;紧凑视觉只能由外层 div 套 fontSize/padding 模拟,无法影响内部间距)",
+        "期待 showSearch prop(搜索是内置默认开启 — 仅 trim 控制空格策略)"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(keys: Array<string>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "穿梭（右→左或左→右）完成时触发：keys 是右侧框所有 key 的当前顺序数组",
+                "上下移动排序后触发：keys 反映排序后的顺序（onSort 也会在此之前触发）",
+                "拖拽排序完成后触发：onEndSort → onChange 顺序触发，keys 是最新右侧顺序"
+            ],
+            "commonMistakes": [
+                "把 onChange 的回参当做 ItemDataProps[] 对象数组——实际是 key 字符串数组",
+                "期望 onChange 在勾选（checkbox）时触发——onChange 只在穿梭/排序完成后触发，不追踪 checkbox 中间状态",
+                "期望 onChange 只在穿梭时触发——排序（onSort）也会同时触发 onChange"
+            ]
+        },
+        "onSort": {
+            "signature": "(keys: Array<string>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "右侧列表拖拽排序结束时触发：keys 是排序后右侧的 key 顺序数组",
+                "点击上/下移动按钮后触发：先触发 onSort 再触发 onChange",
+                "用于服务端保存排序：onSort={(keys) => saveOrder(keys)}"
+            ],
+            "commonMistakes": [
+                "只监听 onSort 不监听 onChange——右侧 key 顺序同时写入了 onChange，两者都会触发",
+                "期望 onSort 在左侧操作时触发——onSort 只针对右侧列表排序，左侧没有排序功能"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "data 的 TypeScript 导出类型名是 IItemDataProps（有 I 前缀），不是 ItemDataProps",
+            "wrong": "import { ItemDataProps } from '@para-ui/core/Transfer'  // 不存在此导出",
+            "right": "import { IItemDataProps } from '@para-ui/core/Transfer'  // src/Transfer/index.tsx 重命名导出"
+        },
+        {
+            "issue": "value 是 string[] 不是 ItemDataProps[]，传对象数组导致右侧显示为空",
+            "wrong": "value={[{ key: 'a', name: '选项A' }]}  // 传对象数组，内部 indexOf 比对会失败",
+            "right": "value={['a']}  // 传 key 字符串数组，对应 data 中每项的 customKey 字段值"
+        },
+        {
+            "issue": "自定义 key 字段时需同步传 customKey，否则 value 比对不到 data",
+            "wrong": "// 数据字段是 id 但没传 customKey\ndata={[{ id: '001', name: '项目A' }]} value={['001']}  // 比对用 data.key，找不到",
+            "right": "data={[{ id: '001', name: '项目A' }]} value={['001']} customKey='id'  // 告知组件用 id 做 key"
+        },
+        {
+            "issue": "render 是副作用 hook 不是 render prop，返回 void 不是 ReactNode",
+            "wrong": "render={(item) => <span>{item.name}</span>}  // 假设 render 返回 ReactNode 渲染到列表项",
+            "right": "// render 用于预处理 item 字段（副作用），自定义列表项显示用 rightIcon\nrender={(item) => { item.name = item.label; }}  // 修改 item 字段"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Transfer",
+        "adapter": null
+    }
+}