@hsu-react/ui 2.5.4 → 2.5.5

package/lib/components/Chart/Pie/Pie3D/index.js

@@ -87,6 +87,12 @@ const ChartPie3D = props => {
   });
   const onChartRef = (0, _useLatestRef.useLatestRef)(onChart);
 
+  // onClick 不进依赖数组：消费方传内联箭头时每次渲染都是新引用，effect 跟着重跑会重建
+  // 3D 饼的 option 并重播动画。注册与否看布尔量（保证「从无到有传入」仍会注册），
+  // 实际调用取 ref 里的最新引用。
+  const onClickRef = (0, _useLatestRef.useLatestRef)(onClick);
+  const hasOnClick = !!onClick;
+
   // 回调 prop 不进依赖数组：消费方传内联箭头时每次渲染都是新引用，effect 会跟着
   // 重跑并再调一次回调 —— 回调里 setState 就是死循环（详见 Input/TextArea 的说明）
   (0, _react.useEffect)(() => {
@@ -106,20 +112,23 @@ const ChartPie3D = props => {
     }
     chart.on("mouseover", handleMouseOver);
     chart.on("globalout", handleGlobalOut);
-    if (onClick) {
-      chart.on("click", onClick);
+    const handleClick = event => {
+      onClickRef.current?.(event);
+    };
+    if (hasOnClick) {
+      chart.on("click", handleClick);
     }
     return () => {
       window.removeEventListener("resize", handleResize);
       if (chart) {
         chart.off("mouseover", handleMouseOver);
         chart.off("globalout", handleGlobalOut);
-        if (onClick) {
-          chart.off("click", onClick);
+        if (hasOnClick) {
+          chart.off("click", handleClick);
         }
       }
     };
-  }, [chartOption, handleResize, handleMouseOver, handleGlobalOut, onChartRef, onClick, containerReady]);
+  }, [chartOption, handleResize, handleMouseOver, handleGlobalOut, onChartRef, onClickRef, hasOnClick, containerReady]);
   (0, _react.useEffect)(() => {
     return () => {
       if (resizeObserverRef.current) {

package/lib/components/Chart/Pie/index.js

@@ -203,6 +203,12 @@ const ChartPie = props => {
   }, []);
   const onChartRef = (0, _useLatestRef.useLatestRef)(onChart);
 
+  // onClick 不进依赖数组：消费方传内联箭头时每次渲染都是新引用，effect 跟着重跑就会
+  // 再走一遍 setOption(notMerge)，动画重播、悬浮/高亮态被清掉。注册与否看布尔量，
+  // 这样「从无到有传入 onClick」仍会注册；实际调用取 ref 里的最新引用。
+  const onClickRef = (0, _useLatestRef.useLatestRef)(onClick);
+  const hasOnClick = !!onClick;
+
   // 回调 prop 不进依赖数组：消费方传内联箭头时每次渲染都是新引用，effect 会跟着
   // 重跑并再调一次回调 —— 回调里 setState 就是死循环（详见 Input/TextArea 的说明）
   // Initialize the chart
@@ -231,8 +237,11 @@ const ChartPie = props => {
     }
 
     // Add click event
-    if (onClick) {
-      chartInstanceRef.current?.on("click", onClick);
+    const handleClick = event => {
+      onClickRef.current?.(event);
+    };
+    if (hasOnClick) {
+      chartInstanceRef.current?.on("click", handleClick);
     }
 
     // Legend auto-scroll
@@ -253,8 +262,8 @@ const ChartPie = props => {
     // Cleanup function
     return () => {
       window.removeEventListener("resize", handleResize);
-      if (onClick) {
-        chartInstanceRef.current?.off("click", onClick);
+      if (hasOnClick) {
+        chartInstanceRef.current?.off("click", handleClick);
       }
 
       // Clean up legend scrolling
@@ -263,7 +272,7 @@ const ChartPie = props => {
         legendScrollRef.current = null;
       }
     };
-  }, [chartOption, handleResize, onChartRef, onClick, enableLegendAutoScroll, seriesData, legendVisibleCount, legendScrollInterval, containerReady]);
+  }, [chartOption, handleResize, onChartRef, onClickRef, hasOnClick, enableLegendAutoScroll, seriesData, legendVisibleCount, legendScrollInterval, containerReady]);
 
   // Clean up resources when the component unmounts
   (0, _react.useEffect)(() => {

package/lib/components/Chart/Sankey/index.js

@@ -8,6 +8,7 @@ var _react = _interopRequireWildcard(require("react"));
 var _useContainerReady = _interopRequireDefault(require("../_hooks/useContainerReady"));
 var _indexModule = _interopRequireDefault(require("../index.module.scss"));
 var echarts = _interopRequireWildcard(require("echarts"));
+var _useLatestRef = _interopRequireDefault(require("../../../hooks/useLatestRef"));
 var _jsxRuntime = require("react/jsx-runtime");
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function (e) { return e ? t : r; })(e); }
@@ -104,6 +105,13 @@ const Sankey = props => {
     return option;
   }, [seriesData, seriesLinks, series]);
 
+  // getImage 只是「出图后把 dataURL 交出去」的出口，既不决定图怎么画，
+  // 也不该决定要不要重画。它进依赖数组会让 effect 跟着重跑 → setOption(notMerge)
+  // → 图重绘 → 再触发一次 finished → 再回调；消费方把图存进 state 就是死循环。
+  // 而且 finished 监听只在首次 init 时注册，闭包里锁死的是首帧的 getImage，
+  // 后续换了引用永远调不到 —— 依赖数组写了它也没用，是条死依赖。走 ref 两个问题一起解决。
+  const getImageRef = (0, _useLatestRef.default)(getImage);
+
   // Callback handling chart resize
   const handleResize = (0, _react.useCallback)(() => {
     // A keep-alive tab losing focus fires the observer with a 0×0 box; resizing to that throws
@@ -125,7 +133,7 @@ const Sankey = props => {
 
       // Attach the finished event listener on first initialization
       chart.on("finished", () => {
-        getImage?.(chart.getDataURL({
+        getImageRef.current?.(chart.getDataURL({
           type: "png",
           pixelRatio: 1,
           backgroundColor: "#fff"
@@ -149,7 +157,7 @@ const Sankey = props => {
     return () => {
       window.removeEventListener("resize", handleResize);
     };
-  }, [chartOption, handleResize, getImage, containerReady]);
+  }, [chartOption, handleResize, getImageRef, containerReady]);
 
   // Clean up resources on unmount
   (0, _react.useEffect)(() => {

package/lib/components/Chart/Tree/index.js

@@ -8,6 +8,7 @@ var _react = _interopRequireWildcard(require("react"));
 var _useContainerReady = _interopRequireDefault(require("../_hooks/useContainerReady"));
 var _indexModule = _interopRequireDefault(require("../index.module.scss"));
 var echarts = _interopRequireWildcard(require("echarts"));
+var _useLatestRef = _interopRequireDefault(require("../../../hooks/useLatestRef"));
 var _hsuUtils = require("hsu-utils");
 var _tree = require("../_utils/tree");
 var _jsxRuntime = require("react/jsx-runtime");
@@ -44,6 +45,13 @@ const Tree = props => {
     return option;
   }, [seriesData, series]);
 
+  // getImage 只是「出图后把 dataURL 交出去」的出口，既不决定图怎么画，
+  // 也不该决定要不要重画。它进依赖数组会让 effect 跟着重跑 → setOption(notMerge)
+  // → 图重绘 → 再触发一次 finished → 再回调；消费方把图存进 state 就是死循环。
+  // 而且 finished 监听只在首次 init 时注册，闭包里锁死的是首帧的 getImage，
+  // 后续换了引用永远调不到 —— 依赖数组写了它也没用，是条死依赖。走 ref 两个问题一起解决。
+  const getImageRef = (0, _useLatestRef.default)(getImage);
+
   // Callback handling chart resize
   const handleResize = (0, _react.useCallback)(() => {
     // A keep-alive tab losing focus fires the observer with a 0×0 box; resizing to that throws
@@ -65,7 +73,7 @@ const Tree = props => {
 
       // Attach the finished event listener on first initialization
       chart.on("finished", () => {
-        getImage?.(chart.getDataURL({
+        getImageRef.current?.(chart.getDataURL({
           type: "png",
           pixelRatio: 1,
           backgroundColor: "#fff"
@@ -89,7 +97,7 @@ const Tree = props => {
     return () => {
       window.removeEventListener("resize", handleResize);
     };
-  }, [chartOption, handleResize, getImage, containerReady]);
+  }, [chartOption, handleResize, getImageRef, containerReady]);
 
   // Clean up resources on unmount
   (0, _react.useEffect)(() => {

package/lib/components/Select/_hooks/useSelectComposition.js

@@ -12,6 +12,7 @@ function useSelectComposition({
   onSearch
 }) {
   const [isComposing, setComposing] = (0, _react.useState)(false);
+  const hasOnSearch = !!onSearch;
   (0, _react.useEffect)(() => {
     const compositionend = () => {
       setComposing(false);
@@ -19,7 +20,7 @@ function useSelectComposition({
     const compositionstart = () => {
       setComposing(true);
     };
-    if (onSearch) {
+    if (hasOnSearch) {
       window.addEventListener("compositionstart", compositionstart);
       window.addEventListener("compositionend", compositionend);
     }
@@ -27,7 +28,10 @@ function useSelectComposition({
       window.removeEventListener("compositionstart", compositionstart);
       window.removeEventListener("compositionend", compositionend);
     };
-  }, [onSearch]);
+    // onSearch 在这里只被当作「要不要监听输入法事件」的真值判断，effect 体从不调它。
+    // 直接进依赖数组的话，消费方传内联箭头就会每渲染一次拆一次、装一次 window 监听；
+    // 只取「有没有传」这个布尔量，从无到有时照样会重新注册。
+  }, [hasOnSearch]);
   return {
     isComposing
   };

package/lib/components/Table/_hooks/useAutoScrolling.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", {
 exports.default = void 0;
 var _ahooks = require("ahooks");
 var _react = require("react");
+var _useLatestRef = require("../../../hooks/useLatestRef");
 const DEFAULT_INTERVAL = 2000;
 const DEFAULT_SPEED = 25;
 const SMOOTH_SCROLL_TICK = 10;
@@ -24,6 +25,13 @@ const useAutoScrolling = props => {
     autoScrollLoopMode = "reset",
     autoScrollingOffset = 0
   } = props;
+
+  // onAutoScrollEndAdd 在这里身兼两职：既是「有没有加载更多」的开关，又是真正去加载的动作。
+  // 整个 rAF 循环（loop → 依赖它 → 启停 effect 依赖 loop）都挂在它的引用上，
+  // 消费方传内联箭头就会每渲染一次重启一次滚动循环 —— 表格滚到一半被打回起点。
+  // 拆成两半：开关看布尔量（从无到有传入时仍会正确接上加载更多），动作取 ref 里的最新引用。
+  const onAutoScrollEndAddRef = (0, _useLatestRef.useLatestRef)(onAutoScrollEndAdd);
+  const hasOnAutoScrollEndAdd = !!onAutoScrollEndAdd;
   const validSpeed = autoScrollingSpeed > 0 ? autoScrollingSpeed : DEFAULT_SPEED;
   const smoothStep = validSpeed * SMOOTH_SCROLL_TICK / 1000;
   const [ready, setReady] = (0, _react.useState)(false);
@@ -237,11 +245,12 @@ const useAutoScrolling = props => {
     }, SMOOTH_SCROLL_TICK);
   }, [bindHover, checkSeamlessReset, clearSmoothTimer, getBody, interval, isAtBottom, isBodyScrollable, isSeamless, smoothStep]);
   const runLoadMore = (0, _react.useCallback)(() => {
-    if (!onAutoScrollEndAdd || pendingLoadMoreRef.current) return;
+    const loadMore = onAutoScrollEndAddRef.current;
+    if (!loadMore || pendingLoadMoreRef.current) return;
     pendingLoadMoreRef.current = true;
     phaseRef.current = "loading";
     const token = ++loadTokenRef.current;
-    onAutoScrollEndAdd().then(hasMore => {
+    loadMore().then(hasMore => {
       if (token !== loadTokenRef.current) return;
       const currentBody = getBody();
       if (hasMore) {
@@ -261,7 +270,7 @@ const useAutoScrolling = props => {
       if (token !== loadTokenRef.current) return;
       pendingLoadMoreRef.current = false;
     });
-  }, [autoScrollLoop, getBody, onAutoScrollEndAdd]);
+  }, [autoScrollLoop, getBody, onAutoScrollEndAddRef]);
   const loop = (0, _react.useCallback)(() => {
     rafRef.current = requestAnimationFrame(loop);
     if (!autoScrolling || !ready || !dataSource?.length || !ref?.current) {
@@ -293,7 +302,7 @@ const useAutoScrolling = props => {
         // In seamless mode the scroll never actually reaches the bottom; just keep scrolling
         phaseRef.current = "idle";
       } else if (isAtBottom(body)) {
-        if (onAutoScrollEndAdd) {
+        if (hasOnAutoScrollEndAdd) {
           runLoadMore();
         } else {
           if (autoScrollLoop) {
@@ -339,7 +348,7 @@ const useAutoScrolling = props => {
       return;
     }
     startSmoothStep(body, targetTop);
-  }, [autoScrollMode, autoScrollLoop, autoScrolling, bindHover, checkSeamlessReset, dataSource, getBody, getRowHeight, interval, isAtBottom, isBodyScrollable, isSeamless, onAutoScrollEndAdd, ready, ref, runLoadMore, setupSeamlessClones, startSmoothStep]);
+  }, [autoScrollMode, autoScrollLoop, autoScrolling, bindHover, checkSeamlessReset, dataSource, getBody, getRowHeight, interval, isAtBottom, isBodyScrollable, isSeamless, hasOnAutoScrollEndAdd, ready, ref, runLoadMore, setupSeamlessClones, startSmoothStep]);
   (0, _react.useEffect)(() => {
     if (!autoScrolling || !ready || !dataSource?.length || !ref?.current) {
       cleanup();
@@ -364,7 +373,7 @@ const useAutoScrolling = props => {
       cleanupClones();
       return;
     }
-    if (onAutoScrollEndAdd) {
+    if (hasOnAutoScrollEndAdd) {
       // In load-more mode, if scrolling had stopped, resume auto-scrolling when new data arrives
       if (phaseRef.current === "stopped") {
         phaseRef.current = autoScrollMode === "row" ? "wait" : "idle";
@@ -377,7 +386,7 @@ const useAutoScrolling = props => {
       phaseRef.current = autoScrollMode === "row" ? "wait" : "idle";
       waitUntilRef.current = autoScrollMode === "row" ? performance.now() + interval : 0;
     }
-  }, [autoScrollMode, cleanupClones, dataSource, getBody, interval, isBodyScrollable, isSeamless, onAutoScrollEndAdd]);
+  }, [autoScrollMode, cleanupClones, dataSource, getBody, interval, isBodyScrollable, isSeamless, hasOnAutoScrollEndAdd]);
   (0, _react.useEffect)(() => {
     if (!autoScrolling || !ref?.current) return;
     let resizeRaf = null;

package/lib/layout/Menu/_hooks/useOnlyLvOneMenu.js

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.useOnlyLvOneMenu = void 0;
 var _react = require("react");
+var _useLatestRef = require("../../../hooks/useLatestRef");
 var _reactRouter = require("react-router");
 /**
  * Handle the top-level-only menu logic
@@ -17,15 +18,20 @@ const useOnlyLvOneMenu = ({
   setMenuKey
 }) => {
   const location = (0, _reactRouter.useLocation)();
+  // getCurrChildItems 是 effect 体里发出去的通知，本身进依赖数组是这一类死循环的标准配方：
+  // 消费方传内联箭头 → 每次渲染新引用 → effect 重跑 → setOpenkeys([item.key]) 每次都是
+  // 新数组必定触发重渲染 → 又是新引用 …… 直到 React 抛 Maximum update depth exceeded。
+  // 通知取 ref 里的最新引用，依赖数组只留真正的输入。
+  const getCurrChildItemsRef = (0, _useLatestRef.useLatestRef)(getCurrChildItems);
   (0, _react.useEffect)(() => {
     if (onlyLvOneMenu) {
       const item = items.find(i => i.key === "/" + location.pathname.split("/").filter(Boolean)[0]);
       if (item) {
-        getCurrChildItems?.(item.children || []);
+        getCurrChildItemsRef.current?.(item.children || []);
         setOpenkeys([item.key]);
         setMenuKey(item.key);
       }
     }
-  }, [items, getCurrChildItems, location, onlyLvOneMenu, setOpenkeys, setMenuKey]);
+  }, [items, getCurrChildItemsRef, location, onlyLvOneMenu, setOpenkeys, setMenuKey]);
 };
 exports.useOnlyLvOneMenu = useOnlyLvOneMenu;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hsu-react/ui",
-  "version": "2.5.4",
+  "version": "2.5.5",
   "description": "一套基于 React + Ant Design 的中后台业务组件库",
   "license": "MIT",
   "type": "module",

package/src/__tests__/callbackDepsGuard.test.ts

@@ -0,0 +1,119 @@
+import fs from "node:fs";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+/**
+ * 防回归守卫：**回调 prop 不许进 effect 依赖数组**。
+ *
+ * 这条缺陷没有任何信号——不报错、不变慢，只是消费方一传内联箭头
+ * （`onXxx={(v) => setV(v)}`，React 里最常见的写法）就重复订阅 / 重复通知，
+ * 严重的直接死循环到 `Maximum update depth exceeded`。
+ * 靠人工 review 拦不住，所以扫源码。
+ *
+ * 正确写法见 `src/hooks/useLatestRef.ts`：
+ * - 调用取 ref 里的最新引用；
+ * - 「有没有传回调」若决定要不要注册监听，就单独拆一个布尔量进依赖数组，
+ *   这样「从无到有传入回调」仍会正确注册。
+ *
+ * 确实无害的写法登记在 ALLOWED 里，每条都要写清为什么无害。
+ */
+
+const SRC = path.resolve(__dirname, "..");
+
+/** 回调型标识符：`onXxx` 形态，外加几个明确的出口型回调名 */
+const EXTRA_CALLBACK_NAMES = new Set(["getImage", "labelRender"]);
+const isCallbackDep = (name: string) =>
+  (/^on[A-Z]/.test(name) && !name.endsWith("Ref")) ||
+  EXTRA_CALLBACK_NAMES.has(name);
+
+/** `文件相对路径::依赖名` → 无害的理由 */
+const ALLOWED: Record<string, string> = {
+  "components/Chat/ChatHistory/index.tsx::onScrollEnd":
+    "只在 DOM scroll 监听里调，effect 体不调它；重订阅是同一节点上摘一个装一个，无副作用",
+  "components/DatePicker/index.tsx::onChange":
+    "纯 ref 同步 effect：effect 体只写 ref，不调回调、不订阅任何东西",
+  "components/DatePicker/RangePicker/index.tsx::onChange":
+    "同上，纯 ref 同步 effect",
+  "components/Tree/index.tsx::onSelectPath": "同上，纯 ref 同步 effect",
+};
+
+function walk(dir: string, out: string[] = []) {
+  for (const name of fs.readdirSync(dir)) {
+    const full = path.join(dir, name);
+    if (fs.statSync(full).isDirectory()) walk(full, out);
+    else if (/\.(tsx?|jsx?)$/.test(name) && !/\.test\./.test(name))
+      out.push(full);
+  }
+  return out;
+}
+
+/** 找出每个 useEffect / useLayoutEffect 的依赖数组，返回 [行号, 依赖名] */
+function effectDeps(src: string): Array<[number, string]> {
+  const found: Array<[number, string]> = [];
+  const re = /use(?:Layout)?Effect\(/g;
+  let m: RegExpExecArray | null;
+
+  while ((m = re.exec(src))) {
+    let i = m.index + m[0].length;
+    let depth = 1;
+    let quote: string | null = null;
+    let prev = "";
+
+    while (i < src.length && depth > 0) {
+      const c = src[i];
+      if (quote) {
+        if (c === quote && prev !== "\\") quote = null;
+      } else if (c === '"' || c === "'" || c === "`") quote = c;
+      else if (c === "(" || c === "[" || c === "{") depth++;
+      else if (c === ")" || c === "]" || c === "}") depth--;
+      prev = c;
+      i++;
+    }
+
+    const body = src.slice(m.index, i).replace(/\)\s*$/, "");
+    const deps = body.match(/,\s*\[([\s\S]*)\]\s*$/);
+    if (!deps) continue;
+
+    const line = src.slice(0, m.index).split("\n").length;
+    for (const raw of deps[1].split(",")) {
+      const name = raw
+        .replace(/\/\/.*$/gm, "")
+        .trim()
+        .split(/[.?[]/)[0]
+        .trim();
+      if (name) found.push([line, name]);
+    }
+  }
+
+  return found;
+}
+
+describe("回调 prop 不进 effect 依赖数组", () => {
+  it("全库无未登记的命中", () => {
+    const offenders: string[] = [];
+
+    for (const file of walk(SRC)) {
+      const rel = path.relative(SRC, file).split(path.sep).join("/");
+      const src = fs.readFileSync(file, "utf8");
+
+      for (const [line, dep] of effectDeps(src)) {
+        if (!isCallbackDep(dep)) continue;
+        if (ALLOWED[`${rel}::${dep}`]) continue;
+        offenders.push(`${rel}:${line}  ${dep}`);
+      }
+    }
+
+    expect(offenders).toEqual([]);
+  });
+
+  it("守卫本身能抓到问题（自测）", () => {
+    const bad = `
+      useEffect(() => {
+        onDone?.();
+      }, [value, onDone]);
+    `;
+    expect(effectDeps(bad).map(([, d]) => d)).toContain("onDone");
+    expect(isCallbackDep("onDone")).toBe(true);
+    expect(isCallbackDep("onDoneRef")).toBe(false);
+  });
+});

package/src/components/ChainGraph/_hooks/callbacks.test.tsx

@@ -0,0 +1,155 @@
+import { describe, expect, it, vi } from "vitest";
+import { act, renderHook } from "@testing-library/react";
+
+vi.mock("../ChainGraphServices", () => ({ default: class {} }));
+
+import { useChainGraphLayout } from "./useChainGraphLayout";
+import { useChainGraphData } from "./useChainGraphData";
+import type ChainGraphServices from "../ChainGraphServices";
+import type { TreeGraphData } from "..";
+
+/**
+ * ChainGraph 把回调交给图实例，由图实例在后续事件里回调。
+ * 这类「出口型」回调进依赖数组，会让消费方传内联箭头时反复触发重排 / 重新 setData。
+ */
+
+const DATA = { id: "root", label: "root" } as unknown as TreeGraphData;
+
+describe("useChainGraphLayout", () => {
+  const makeGraph = () =>
+    ({ changeLayout: vi.fn() }) as unknown as ChainGraphServices & {
+      changeLayout: ReturnType<typeof vi.fn>;
+    };
+
+  it("getImage 换引用不会重新 changeLayout（整张图重排）", () => {
+    const graph = makeGraph();
+    const { rerender } = renderHook(
+      ({ getImage }: { getImage?: (img: string) => void }) =>
+        useChainGraphLayout({ graph, octopus: true, rootLevel: 0, getImage }),
+      { initialProps: { getImage: vi.fn() } },
+    );
+
+    expect(graph.changeLayout).toHaveBeenCalledTimes(1);
+
+    rerender({ getImage: vi.fn() });
+    rerender({ getImage: vi.fn() });
+
+    expect(graph.changeLayout).toHaveBeenCalledTimes(1);
+  });
+
+  it("出图时调到的是最新的 getImage，包括从无到有传入的情况", () => {
+    const graph = makeGraph();
+    const { rerender } = renderHook(
+      ({ getImage }: { getImage?: (img: string) => void }) =>
+        useChainGraphLayout({ graph, octopus: true, rootLevel: 0, getImage }),
+      { initialProps: {} as { getImage?: (img: string) => void } },
+    );
+
+    const forwarded = graph.changeLayout.mock.calls[0][2] as (
+      img: string,
+    ) => void;
+    // 没传回调时转发函数照样存在，调用不报错
+    expect(() => forwarded("img-0")).not.toThrow();
+
+    const later = vi.fn();
+    rerender({ getImage: later });
+    // 图实例里存的还是同一个转发函数，但它现在会转给新传入的回调
+    forwarded("img-1");
+    expect(later).toHaveBeenCalledWith("img-1");
+  });
+});
+
+describe("useChainGraphData", () => {
+  const makeGraph = () =>
+    ({ setData: vi.fn() }) as unknown as ChainGraphServices & {
+      setData: ReturnType<typeof vi.fn>;
+    };
+
+  type Props = {
+    getImage?: (img: string) => void;
+    labelRender?: (label: TreeGraphData) => string;
+    onLayoutingChange?: (v: boolean) => void;
+  };
+
+  it("三个回调换引用都不会重新 setData", () => {
+    const graph = makeGraph();
+    const { rerender } = renderHook(
+      (props: Props) => useChainGraphData({ graph, data: DATA, ...props }),
+      {
+        initialProps: {
+          getImage: vi.fn(),
+          labelRender: vi.fn(() => "a"),
+          onLayoutingChange: vi.fn(),
+        } as Props,
+      },
+    );
+
+    expect(graph.setData).toHaveBeenCalledTimes(1);
+
+    rerender({
+      getImage: vi.fn(),
+      labelRender: vi.fn(() => "b"),
+      onLayoutingChange: vi.fn(),
+    });
+
+    expect(graph.setData).toHaveBeenCalledTimes(1);
+  });
+
+  it("图实例回调时取到的是最新引用，不是首次 setData 时的那个", () => {
+    const graph = makeGraph();
+    const firstLabel = vi.fn(() => "first");
+    const { rerender } = renderHook(
+      (props: Props) => useChainGraphData({ graph, data: DATA, ...props }),
+      {
+        initialProps: {
+          getImage: vi.fn(),
+          labelRender: firstLabel,
+          onLayoutingChange: vi.fn(),
+        } as Props,
+      },
+    );
+
+    const pushed = graph.setData.mock.calls[0][0] as {
+      getImage: (img: string) => void;
+      labelRender?: (label: TreeGraphData) => string;
+      isLayouting: (v: boolean) => void;
+    };
+
+    const nextImage = vi.fn();
+    const nextLabel = vi.fn(() => "next");
+    const nextLayouting = vi.fn();
+    rerender({
+      getImage: nextImage,
+      labelRender: nextLabel,
+      onLayoutingChange: nextLayouting,
+    });
+
+    pushed.getImage("img");
+    expect(nextImage).toHaveBeenCalledWith("img");
+
+    expect(pushed.labelRender!(DATA)).toBe("next");
+    expect(firstLabel).not.toHaveBeenCalled();
+
+    act(() => pushed.isLayouting(false));
+    expect(nextLayouting).toHaveBeenCalledWith(false);
+  });
+
+  it("labelRender 的「传了才改写 label」语义保留：没传就是 undefined，从无到有会带上", () => {
+    const graph = makeGraph();
+    const { rerender } = renderHook(
+      ({ data, labelRender }: { data: TreeGraphData; labelRender?: Props["labelRender"] }) =>
+        useChainGraphData({ graph, data, labelRender }),
+      { initialProps: { data: DATA } as { data: TreeGraphData; labelRender?: Props["labelRender"] } },
+    );
+
+    expect(graph.setData.mock.calls[0][0].labelRender).toBeUndefined();
+
+    const label = vi.fn(() => "x");
+    const nextData = { id: "root2", label: "root2" } as unknown as TreeGraphData;
+    rerender({ data: nextData, labelRender: label });
+
+    expect(graph.setData).toHaveBeenCalledTimes(2);
+    expect(typeof graph.setData.mock.calls[1][0].labelRender).toBe("function");
+    expect(graph.setData.mock.calls[1][0].labelRender(DATA)).toBe("x");
+  });
+});

package/src/components/ChainGraph/_hooks/useChainGraphData.ts

@@ -1,7 +1,8 @@
-import { useEffect, useState } from "react";
+import { useCallback, useEffect, useState } from "react";
 import { Equal } from "hsu-utils";
 import ChainGraphServices from "../ChainGraphServices";
 import { TreeGraphData } from "..";
+import { useLatestRef } from "../../../hooks/useLatestRef";
 
 interface UseChainGraphDataProps {
   graph: ChainGraphServices | null;
@@ -28,6 +29,35 @@ export function useChainGraphData(props: UseChainGraphDataProps) {
   );
   const [isLayouting, setIsLayouting] = useState(true);
 
+  // 这三个回调都是「交给图实例、由它在后续事件里回调」的出口，不是数据本身。
+  // 它们进依赖数组是条死依赖：effect 体被 ObjEqual(lastData, data) 挡住，
+  // 引用变了也不会重新 setData —— 图里存的还是首次 setData 时那个闭包，
+  // 换了引用永远调不到（stale closure）。改成引用恒定的转发函数：
+  // 依赖数组只留真正的输入（graph/data/level/rootLevel），调用时总是取到最新的回调。
+  const getImageRef = useLatestRef(getImage);
+  const labelRenderRef = useLatestRef(labelRender);
+  const onLayoutingChangeRef = useLatestRef(onLayoutingChange);
+
+  const emitImage = useCallback(
+    (img: string) => {
+      getImageRef.current?.(img);
+    },
+    [getImageRef]
+  );
+  // labelRender 在 ChainGraphServices.setData 里是「传了才改写 label」的真值判断，
+  // 所以这里保留「有没有传」的语义：没传就传 undefined，传了才给转发函数。
+  const renderLabel = useCallback(
+    (label: TreeGraphData) => labelRenderRef.current!(label),
+    [labelRenderRef]
+  );
+  const emitLayouting = useCallback(
+    (value: boolean) => {
+      setIsLayouting(value);
+      onLayoutingChangeRef.current?.(value);
+    },
+    [onLayoutingChangeRef]
+  );
+
   useEffect(() => {
     if (graph && !Equal.ObjEqual(lastData, data)) {
       setLastData(data);
@@ -35,12 +65,9 @@ export function useChainGraphData(props: UseChainGraphDataProps) {
         data,
         level,
         rootLevel,
-        getImage,
-        isLayouting: (value) => {
-          setIsLayouting(value);
-          onLayoutingChange?.(value);
-        },
-        labelRender,
+        getImage: emitImage,
+        isLayouting: emitLayouting,
+        labelRender: labelRenderRef.current ? renderLabel : undefined,
       });
     }
   }, [
@@ -48,10 +75,11 @@ export function useChainGraphData(props: UseChainGraphDataProps) {
     data,
     level,
     rootLevel,
-    getImage,
-    labelRender,
-    onLayoutingChange,
     lastData,
+    emitImage,
+    emitLayouting,
+    renderLabel,
+    labelRenderRef,
   ]);
 
   return { isLayouting };