@hsu-react/ui 2.5.5 → 2.5.6

package/lib/hooks/useShallowStable.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 把一个**内容没变、但每次渲染都新建**的对象收敛成**引用恒定**的对象：
+ * 浅比较（自有键 ＋ `Object.is` 比值）相等就继续返回上一次那个引用。
+ *
+ * 用途只有一个：让它可以直接进 `useMemo` / `useEffect` 的依赖数组。
+ *
+ * React 的依赖数组按 `Object.is` 比引用，所以依赖里只要混进一个「每次渲染都新建
+ * 的对象」，memo 就**恒不命中**、effect 就**每渲染必重跑**。组件内部最容易出现
+ * 这种对象的地方是 rest 解构：
+ *
+ * ```tsx
+ * const { className, style, ...coreOption } = props; // coreOption 每次都是新对象
+ * const option = useMemo(() => ({ ...coreOption }), [coreOption]); // 永远不命中
+ * ```
+ *
+ * 消费方就算把每一个 prop 都 memo 好，也躲不掉——新对象是组件自己建的。
+ * 正确写法是让这个对象回到值语义：
+ *
+ * ```tsx
+ * const { className, style, ...restOption } = props;
+ * const coreOption = useShallowStable(restOption); // 内容不变 → 引用不变
+ * ```
+ *
+ * 注意这**不是**「缓存结果跳过副作用」：memo 该重算时照样重算、effect 该重跑时
+ * 照样重跑——只要 rest 里任何一个值真的变了，浅比较就不相等，新引用立刻透出去。
+ *
+ * 渲染期间读写 ref 的安全性：并发渲染下被丢弃的那次渲染可能已经把 ref 换成了它
+ * 自己的对象，但那个对象与当次 props 浅相等，所以后续渲染拿到的引用**内容永远
+ * 与当前 props 一致**，不会读到过期值。
+ */
+export declare function useShallowStable<T extends object>(value: T): T;
+export default useShallowStable;

package/lib/hooks/useShallowStable.js

@@ -0,0 +1,59 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+exports.useShallowStable = useShallowStable;
+var _react = require("react");
+/**
+ * 把一个**内容没变、但每次渲染都新建**的对象收敛成**引用恒定**的对象：
+ * 浅比较（自有键 ＋ `Object.is` 比值）相等就继续返回上一次那个引用。
+ *
+ * 用途只有一个：让它可以直接进 `useMemo` / `useEffect` 的依赖数组。
+ *
+ * React 的依赖数组按 `Object.is` 比引用，所以依赖里只要混进一个「每次渲染都新建
+ * 的对象」，memo 就**恒不命中**、effect 就**每渲染必重跑**。组件内部最容易出现
+ * 这种对象的地方是 rest 解构：
+ *
+ * ```tsx
+ * const { className, style, ...coreOption } = props; // coreOption 每次都是新对象
+ * const option = useMemo(() => ({ ...coreOption }), [coreOption]); // 永远不命中
+ * ```
+ *
+ * 消费方就算把每一个 prop 都 memo 好，也躲不掉——新对象是组件自己建的。
+ * 正确写法是让这个对象回到值语义：
+ *
+ * ```tsx
+ * const { className, style, ...restOption } = props;
+ * const coreOption = useShallowStable(restOption); // 内容不变 → 引用不变
+ * ```
+ *
+ * 注意这**不是**「缓存结果跳过副作用」：memo 该重算时照样重算、effect 该重跑时
+ * 照样重跑——只要 rest 里任何一个值真的变了，浅比较就不相等，新引用立刻透出去。
+ *
+ * 渲染期间读写 ref 的安全性：并发渲染下被丢弃的那次渲染可能已经把 ref 换成了它
+ * 自己的对象，但那个对象与当次 props 浅相等，所以后续渲染拿到的引用**内容永远
+ * 与当前 props 一致**，不会读到过期值。
+ */
+function useShallowStable(value) {
+  const ref = (0, _react.useRef)(value);
+  if (!shallowEqual(ref.current, value)) {
+    ref.current = value;
+  }
+  return ref.current;
+}
+function shallowEqual(a, b) {
+  if (Object.is(a, b)) return true;
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const key of aKeys) {
+    if (!Object.prototype.hasOwnProperty.call(b, key)) return false;
+    if (!Object.is(a[key], b[key])) {
+      return false;
+    }
+  }
+  return true;
+}
+var _default = exports.default = useShallowStable;

package/package.json

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

package/src/__tests__/callbackDepsGuard.test.ts

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
+import { hookDeps, walkSources } from "./depsScan";
 
 /**
  * 防回归守卫：**回调 prop 不许进 effect 依赖数组**。
@@ -37,62 +38,14 @@ const ALLOWED: Record<string, string> = {
   "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;
-}
+const EFFECT_RE = /use(?:Layout)?Effect\(/g;
+const effectDeps = (src: string) => hookDeps(src, EFFECT_RE);
 
 describe("回调 prop 不进 effect 依赖数组", () => {
   it("全库无未登记的命中", () => {
     const offenders: string[] = [];
 
-    for (const file of walk(SRC)) {
+    for (const file of walkSources(SRC)) {
       const rel = path.relative(SRC, file).split(path.sep).join("/");
       const src = fs.readFileSync(file, "utf8");
 

package/src/__tests__/depsScan.ts

@@ -0,0 +1,158 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * 两条防回归守卫（`callbackDepsGuard` / `freshObjectDepsGuard`）共用的源码扫描工具。
+ * 只做静态文本扫描，故意不引入 AST 依赖——守卫本身要足够轻，才不会被人嫌慢删掉。
+ */
+
+/** 去掉注释再扫描：文档注释里的示例代码不是真实代码，不能算命中 */
+export function stripComments(src: string) {
+  let out = "";
+  let i = 0;
+  let quote: string | null = null;
+  while (i < src.length) {
+    const c = src[i];
+    const next = src[i + 1];
+    if (quote) {
+      out += c;
+      if (c === "\\") {
+        out += next ?? "";
+        i += 2;
+        continue;
+      }
+      if (c === quote) quote = null;
+      i++;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === "`") {
+      quote = c;
+      out += c;
+      i++;
+      continue;
+    }
+    if (c === "/" && next === "/") {
+      while (i < src.length && src[i] !== "\n") i++;
+      continue;
+    }
+    if (c === "/" && next === "*") {
+      i += 2;
+      // 把块注释里的换行原样留下，报出来的行号才对得上
+      while (i < src.length && !(src[i] === "*" && src[i + 1] === "/")) {
+        if (src[i] === "\n") out += "\n";
+        i++;
+      }
+      i += 2;
+      continue;
+    }
+    out += c;
+    i++;
+  }
+  return out;
+}
+
+/** 遍历 `src/` 下的源码文件；守卫自己的目录不参与扫描 */
+export function walkSources(dir: string, out: string[] = []) {
+  for (const name of fs.readdirSync(dir)) {
+    if (name === "__tests__") continue;
+    const full = path.join(dir, name);
+    if (fs.statSync(full).isDirectory()) walkSources(full, out);
+    else if (/\.(tsx?|jsx?)$/.test(name) && !/\.test\./.test(name))
+      out.push(full);
+  }
+  return out;
+}
+
+/**
+ * 找出每个匹配 `hookRe` 的 hook 调用的依赖数组，返回 `[行号, 依赖名]`。
+ * `hookRe` 必须带 `g`，且以 `\(` 结尾（例如 `/use(?:Layout)?Effect\(/g`）。
+ */
+export function hookDeps(
+  src: string,
+  hookRe: RegExp,
+): Array<[number, string]> {
+  const found: Array<[number, string]> = [];
+  const re = new RegExp(hookRe.source, "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;
+}
+
+/**
+ * 找出「每次渲染都会新建一个对象/数组」的解构绑定，返回 `绑定名 → 说明`。
+ *
+ * 两种形态：
+ * - rest 包：`const { a, ...rest } = props` —— `rest` 每次都是新对象；
+ * - 字面量默认值：`const { list = [] } = props` —— 消费方没传时每次都是新数组。
+ */
+export function freshObjectBindings(src: string): Map<string, string> {
+  const found = new Map<string, string>();
+
+  const re = /\b(?:const|let|var)\s*\{/g;
+  let m: RegExpExecArray | null;
+
+  while ((m = re.exec(src))) {
+    // 取出与 `{` 配对的那一段解构模式
+    let i = re.lastIndex;
+    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++;
+    }
+    // 后面必须紧跟 `=`，否则不是解构赋值
+    if (!/^\s*=/.test(src.slice(i))) continue;
+
+    const pattern = src.slice(re.lastIndex, i - 1);
+
+    for (const r of pattern.matchAll(/\.\.\.\s*([A-Za-z_$][\w$]*)/g)) {
+      found.set(r[1], "rest 解构包：每次渲染都是新对象");
+    }
+    for (const r of pattern.matchAll(
+      /([A-Za-z_$][\w$]*)\s*=\s*(?:[[{])/g,
+    )) {
+      found.set(r[1], "解构默认值是对象/数组字面量：不传时每次渲染都是新对象");
+    }
+  }
+
+  return found;
+}

package/src/__tests__/freshObjectDepsGuard.test.ts

@@ -0,0 +1,144 @@
+import path from "node:path";
+import fs from "node:fs";
+import { describe, expect, it } from "vitest";
+import {
+  freshObjectBindings,
+  hookDeps,
+  stripComments,
+  walkSources,
+} from "./depsScan";
+
+/**
+ * 防回归守卫：**每次渲染都新建的对象不许进 hook 依赖数组**。
+ *
+ * React 的依赖数组按 `Object.is` 比引用。依赖里只要有一个「组件自己每次渲染新建
+ * 的对象」，`useMemo` 就**恒不命中**、`useEffect` 就**每渲染必重跑**。
+ * 组件内部最常见的两个来源：
+ *
+ * ```tsx
+ * const { className, ...coreOption } = props;   // rest 包，每次都是新对象
+ * const { inRangeColor = ["#fff"] } = props;    // 字面量默认值，不传时每次都是新数组
+ * ```
+ *
+ * 这条缺陷和回调那条一样没有任何信号：不报错、不崩，只是图表每渲染一次就
+ * `setOption(notMerge)` 整个重设——动画重播、鼠标悬浮态被清掉，人工 review 拦不住。
+ *
+ * 正确写法：
+ * - rest 包 → `useShallowStable(rest)`（见 `src/hooks/useShallowStable.ts`）；
+ * - 字面量默认值 → 提到模块级常量。
+ */
+
+const SRC = path.resolve(__dirname, "..");
+const HOOK_RE = /use(?:Memo|Callback|(?:Layout)?Effect)\(/g;
+
+/** `文件相对路径::依赖名` → 无害的理由（确实无害才登记这里） */
+const ALLOWED: Record<string, string> = {};
+
+/**
+ * 存量欠账：守卫上线（2.5.6）时就已经存在的命中。**它们不是无害的**，只是不在这
+ * 一轮的改动范围内（这轮只修 Chart 一族）。修法与 Chart 相同：rest 包走
+ * `useShallowStable`，字面量默认值提到模块级常量。
+ *
+ * 这份名单**只许变短**——下面「只许变短」那条用例会在某项修好却忘了删时报错。
+ * 新写的代码一律直接失败，不许往这里加。
+ */
+const KNOWN_DEBT = [
+  "components/Checkbox/CheckboxGroup/index.tsx::options",
+  "components/FormItem/FormCodeMirror/index.tsx::rules",
+  "components/FormItem/ItemContainer/index.tsx::tipsConfig",
+  "components/Operate/index.tsx::menu",
+  "components/Pagination/index.tsx::pageSizeOptions",
+  "components/Panel/ListPanel/ListModalPanel/index.tsx::modalConfig",
+  "components/Search/_hooks/useSearchCommon.ts::moreSearchItems",
+  "components/Select/AutoCompleteSelect/index.tsx::options",
+  "components/Spreadsheet/index.tsx::xOptionsRest",
+  "components/Table/_hooks/useTableColumns.tsx::columns",
+  "components/Tree/index.tsx::treeData",
+];
+
+interface Hit {
+  /** `文件相对路径::依赖名` */
+  key: string;
+  file: string;
+  line: number;
+  why: string;
+}
+
+function scan(): Hit[] {
+  const hits: Hit[] = [];
+
+  for (const file of walkSources(SRC)) {
+    const rel = path.relative(SRC, file).split(path.sep).join("/");
+    const src = stripComments(fs.readFileSync(file, "utf8"));
+    const fresh = freshObjectBindings(src);
+    if (!fresh.size) continue;
+
+    for (const [line, dep] of hookDeps(src, HOOK_RE)) {
+      const why = fresh.get(dep);
+      if (!why) continue;
+      hits.push({ key: `${rel}::${dep}`, file: rel, line, why });
+    }
+  }
+
+  return hits;
+}
+
+describe("每次渲染都新建的对象不进 hook 依赖数组", () => {
+  it("全库无未登记的新命中", () => {
+    const offenders = scan()
+      .filter(({ key }) => !ALLOWED[key] && !KNOWN_DEBT.includes(key))
+      .map(({ file, line, why }) => `${file}:${line}  ${why}`);
+
+    expect(offenders).toEqual([]);
+  });
+
+  it("Chart 一族一条都不剩（这一轮修的就是它）", () => {
+    const chartHits = scan()
+      .filter(({ file }) => file.startsWith("components/Chart/"))
+      .map(({ key, line }) => `${key}@${line}`);
+
+    expect(chartHits).toEqual([]);
+  });
+
+  it("存量欠账名单只许变短", () => {
+    const live = new Set(scan().map(({ key }) => key));
+    // 修好了就把它从 KNOWN_DEBT 里删掉，别留着已经不存在的条目
+    expect(KNOWN_DEBT.filter((key) => !live.has(key))).toEqual([]);
+  });
+
+  it("守卫本身能抓到问题（自测）", () => {
+    const restCase = `
+      const { className, ...coreOption } = props;
+      const option = useMemo(() => ({ ...coreOption }), [coreOption]);
+    `;
+    expect(freshObjectBindings(restCase).has("coreOption")).toBe(true);
+    expect(hookDeps(restCase, HOOK_RE).map(([, d]) => d)).toContain(
+      "coreOption",
+    );
+
+    const defaultCase = `
+      const { colors = ["#fff"], size = { w: 1 }, name = "x" } = props;
+      useEffect(() => {}, [colors, size, name]);
+    `;
+    const fresh = freshObjectBindings(defaultCase);
+    expect(fresh.has("colors")).toBe(true);
+    expect(fresh.has("size")).toBe(true);
+    // 原始值默认值不是新对象，不该被误判
+    expect(fresh.has("name")).toBe(false);
+
+    // 稳定引用（useShallowStable 的返回值 / 模块级常量）不该被误判
+    const fixed = `
+      const { className, ...restOption } = props;
+      const coreOption = useShallowStable(restOption);
+      const option = useMemo(() => ({ ...coreOption }), [coreOption]);
+    `;
+    expect(freshObjectBindings(fixed).has("coreOption")).toBe(false);
+
+    // 注释里的示例代码不算命中
+    expect(
+      freshObjectBindings(
+        stripComments(`/** const { ...coreOption } = props; */\nconst a = 1;`),
+      ).size,
+    ).toBe(0);
+  });
+});

package/src/components/Chart/Bar/index.tsx

@@ -25,6 +25,7 @@ import {
 import { resolveChartChrome } from "../_utils/chartTheme";
 import useIsDark from "../../../hooks/useIsDark";
 import useLatestRef from "../../../hooks/useLatestRef";
+import useShallowStable from "../../../hooks/useShallowStable";
 
 export interface ChartBarProps extends ChartCommonProps {
   chartTitle?: string;
@@ -70,8 +71,12 @@ const ChartBar: React.FC<ChartBarProps> = (props) => {
     enableLegendAutoScroll = false,
     legendVisibleCount = 8,
     legendScrollInterval = 1500,
-    ...coreOption
+    ...restOption
   } = props;
+  // rest 解构出来的对象每次渲染都是新引用，直接进依赖数组会让 chartOption 的 memo
+  // 恒不命中 —— 父组件每渲染一次就重跑一次 setOption(notMerge)，动画重播、悬浮态被清掉。
+  // useShallowStable 让它回到值语义：内容浅相等就复用同一引用，真变了立刻透出新引用。
+  const coreOption = useShallowStable(restOption);
   const chartRef = useRef<HTMLDivElement>(null);
   const chartInstanceRef = useRef<echarts.ECharts | null>(null);
   // Defers `echarts.init` until the container has a box — see the hook for why

package/src/components/Chart/Bubble/index.tsx

@@ -13,6 +13,7 @@ import {
   drawCircles,
 } from "../_utils/bubble";
 import { useLatestRef } from "../../../hooks/useLatestRef";
+import useShallowStable from "../../../hooks/useShallowStable";
 
 export interface BubbleDataItem {
   name: string;
@@ -71,8 +72,12 @@ const Bubble: React.FC<ChartBubbleProps> = (props) => {
     title,
     onChart,
     onClick,
-    ...coreOption
+    ...restOption
   } = props;
+  // rest 解构出来的对象每次渲染都是新引用，直接进依赖数组会让 chartOption 的 memo
+  // 恒不命中 —— 父组件每渲染一次就重跑一次 setOption(notMerge)，动画重播、悬浮态被清掉。
+  // useShallowStable 让它回到值语义：内容浅相等就复用同一引用，真变了立刻透出新引用。
+  const coreOption = useShallowStable(restOption);
   const chartRef = useRef<HTMLDivElement>(null);
   const chartInstanceRef = useRef<echarts.ECharts | null>(null);
   const resizeObserverRef = useRef<ResizeObserver | null>(null);

package/src/components/Chart/Common/index.tsx

@@ -4,9 +4,14 @@ import styles from "../index.module.scss";
 import { ChartCommonProps, ChartOptionType, ChartsOption } from "..";
 import * as echarts from "echarts";
 import { useLatestRef } from "../../../hooks/useLatestRef";
+import useShallowStable from "../../../hooks/useShallowStable";
 
 const Common: React.FC<ChartCommonProps> = (props) => {
-  const { className, style, onChart, ...coreOption } = props;
+  const { className, style, onChart, ...restOption } = props;
+  // rest 解构出来的对象每次渲染都是新引用，直接进依赖数组会让 chartOption 的 memo
+  // 恒不命中 —— 父组件每渲染一次就重跑一次 setOption(notMerge)，动画重播、悬浮态被清掉。
+  // useShallowStable 让它回到值语义：内容浅相等就复用同一引用，真变了立刻透出新引用。
+  const coreOption = useShallowStable(restOption);
   const chartRef = useRef<HTMLDivElement>(null);
   const chartInstanceRef = useRef<echarts.ECharts | null>(null);
   // Defers `echarts.init` until the container has a box — see the hook for why

package/src/components/Chart/Gauge/index.tsx

@@ -10,6 +10,7 @@ import {
 import React, { useCallback, useEffect, useMemo, useRef } from "react";
 
 import styles from "../index.module.scss";
+import useShallowStable from "../../../hooks/useShallowStable";
 
 export interface ChartGaugeProps extends ChartCommonProps {
   color?: string[] | string;
@@ -28,8 +29,12 @@ const Gauge: React.FC<ChartGaugeProps> = (props) => {
     axisLabel,
     title,
     color = "#1675FB",
-    ...coreSeries
+    ...restSeries
   } = series as echarts.GaugeSeriesOption;
+  // rest 解构出来的对象每次渲染都是新引用，直接进依赖数组会让 chartOption 的 memo
+  // 恒不命中 —— 父组件每渲染一次就重跑一次 setOption(notMerge)，动画重播、悬浮态被清掉。
+  // useShallowStable 让它回到值语义：内容浅相等就复用同一引用，真变了立刻透出新引用。
+  const coreSeries = useShallowStable(restSeries);
   const chartRef = useRef<HTMLDivElement>(null);
   const chartInstanceRef = useRef<echarts.ECharts | null>(null);
   // Defers `echarts.init` until the container has a box — see the hook for why

package/src/components/Chart/Heatmap/index.tsx

@@ -10,6 +10,7 @@ import {
 import { resolveChartChrome } from "../_utils/chartTheme";
 import useIsDark from "../../../hooks/useIsDark";
 import { useLatestRef } from "../../../hooks/useLatestRef";
+import useShallowStable from "../../../hooks/useShallowStable";
 
 export interface HeatmapDataItem {
   /** X-axis index or name */
@@ -43,6 +44,19 @@ export interface ChartHeatmapProps extends ChartCommonProps {
   inRangeColor?: string[];
 }
 
+// 解构默认值写成字面量会每次渲染新建一个数组，进依赖数组就让 memo 恒不命中；提到模块级常量
+const DEFAULT_IN_RANGE_COLOR = [
+  "#8BCCFB",
+  "#75C3FB",
+  "#5AB5F6",
+  "#42AEFA",
+  "#2DA1F5",
+  "#0F89E1",
+  "#056FBB",
+  "#025794",
+  "#0A4089",
+];
+
 const Heatmap: React.FC<ChartHeatmapProps> = (props) => {
   const {
     className,
@@ -61,19 +75,13 @@ const Heatmap: React.FC<ChartHeatmapProps> = (props) => {
     onChart,
     onClick,
     zeroColor,
-    inRangeColor = [
-      "#8BCCFB",
-      "#75C3FB",
-      "#5AB5F6",
-      "#42AEFA",
-      "#2DA1F5",
-      "#0F89E1",
-      "#056FBB",
-      "#025794",
-      "#0A4089",
-    ],
-    ...coreOption
+    inRangeColor = DEFAULT_IN_RANGE_COLOR,
+    ...restOption
   } = props;
+  // rest 解构出来的对象每次渲染都是新引用，直接进依赖数组会让 chartOption 的 memo
+  // 恒不命中 —— 父组件每渲染一次就重跑一次 setOption(notMerge)，动画重播、悬浮态被清掉。
+  // useShallowStable 让它回到值语义：内容浅相等就复用同一引用，真变了立刻透出新引用。
+  const coreOption = useShallowStable(restOption);
   const chartRef = useRef<HTMLDivElement>(null);
   const chartInstanceRef = useRef<echarts.ECharts | null>(null);
   // Defers `echarts.init` until the container has a box — see the hook for why

package/src/components/Chart/Line/index.tsx

@@ -25,6 +25,7 @@ import {
 import { resolveChartChrome } from "../_utils/chartTheme";
 import useIsDark from "../../../hooks/useIsDark";
 import useLatestRef from "../../../hooks/useLatestRef";
+import useShallowStable from "../../../hooks/useShallowStable";
 
 export interface ChartLineProps extends ChartCommonProps {
   chartTitle?: string;
@@ -71,8 +72,12 @@ const ChartLine: React.FC<ChartLineProps> = (props) => {
     enableLegendAutoScroll = false,
     legendVisibleCount = 8,
     legendScrollInterval = 1500,
-    ...coreOption
+    ...restOption
   } = props;
+  // rest 解构出来的对象每次渲染都是新引用，直接进依赖数组会让 chartOption 的 memo
+  // 恒不命中 —— 父组件每渲染一次就重跑一次 setOption(notMerge)，动画重播、悬浮态被清掉。
+  // useShallowStable 让它回到值语义：内容浅相等就复用同一引用，真变了立刻透出新引用。
+  const coreOption = useShallowStable(restOption);
   const chartRef = useRef<HTMLDivElement>(null);
   const chartInstanceRef = useRef<echarts.ECharts | null>(null);
   // Defers `echarts.init` until the container has a box — see the hook for why

package/src/components/Chart/Pie/Pie3D/index.tsx

@@ -8,6 +8,7 @@ import { useMouseOverHandler, useGlobalOutHandler } from "./_hooks";
 import { getPie3DOption } from "./_utils/option";
 import styles from "../../index.module.scss";
 import { useLatestRef } from "../../../../hooks/useLatestRef";
+import useShallowStable from "../../../../hooks/useShallowStable";
 
 export interface Pie3DDataItem {
   name: string;
@@ -86,6 +87,10 @@ export interface SeriesItem {
   };
 }
 
+// 解构默认值写成字面量会每次渲染新建一个对象，进依赖数组就让 memo 恒不命中；提到模块级常量
+const DEFAULT_TOOLTIP = { show: false };
+const DEFAULT_LABEL: LabelConfig = { show: true };
+
 const ChartPie3D: React.FC<ChartPie3DProps> = (props) => {
   const {
     className,
@@ -100,13 +105,17 @@ const ChartPie3D: React.FC<ChartPie3DProps> = (props) => {
     minHeight = 1,
     maxHeight = 10,
     yOffset = -0.2,
-    tooltip = { show: false },
-    label = { show: true },
+    tooltip = DEFAULT_TOOLTIP,
+    label = DEFAULT_LABEL,
     enableMouseControl = false,
     onChart,
     onClick,
-    ...coreOption
+    ...restOption
   } = props;
+  // rest 解构出来的对象每次渲染都是新引用，直接进依赖数组会让 chartOption 的 memo
+  // 恒不命中 —— 父组件每渲染一次就重跑一次 setOption(notMerge)，动画重播、悬浮态被清掉。
+  // useShallowStable 让它回到值语义：内容浅相等就复用同一引用，真变了立刻透出新引用。
+  const coreOption = useShallowStable(restOption);
 
   const chartRef = useRef<HTMLDivElement>(null);
   const chartInstanceRef = useRef<echarts.ECharts | null>(null);