@hsu-react/ui 2.4.1 → 2.4.2

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

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var _react = _interopRequireWildcard(require("react"));
+var _useContainerReady = _interopRequireDefault(require("../_hooks/useContainerReady"));
 var _indexModule = _interopRequireDefault(require("../index.module.scss"));
 var echarts = _interopRequireWildcard(require("echarts"));
 var _jsxRuntime = require("react/jsx-runtime");
@@ -20,6 +21,8 @@ const Common = props => {
   } = props;
   const chartRef = (0, _react.useRef)(null);
   const chartInstanceRef = (0, _react.useRef)(null);
+  // Defers `echarts.init` until the container has a box — see the hook for why
+  const containerReady = (0, _useContainerReady.default)(chartRef);
   const resizeObserverRef = (0, _react.useRef)(null);
 
   // Cache the chart configuration with useMemo
@@ -32,12 +35,16 @@ const Common = props => {
 
   // Callback that handles 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
+    // the laid-out canvas away and it has to be rebuilt when the tab comes back
+    const el = chartRef.current;
+    if (!el || el.clientWidth === 0 || el.clientHeight === 0) return;
     chartInstanceRef.current?.resize();
   }, []);
 
   // Initialize the chart
   (0, _react.useEffect)(() => {
-    if (!chartRef.current) return;
+    if (!chartRef.current || !containerReady) return;
 
     // Initialize or reuse an existing instance
     let chart = chartInstanceRef.current;
@@ -65,7 +72,7 @@ const Common = props => {
     return () => {
       window.removeEventListener("resize", handleResize);
     };
-  }, [chartOption, handleResize, onChart]);
+  }, [chartOption, handleResize, onChart, containerReady]);
 
   // Clean up resources on component unmount
   (0, _react.useEffect)(() => {

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

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var echarts = _interopRequireWildcard(require("echarts"));
+var _useContainerReady = _interopRequireDefault(require("../_hooks/useContainerReady"));
 var _react = _interopRequireWildcard(require("react"));
 var _indexModule = _interopRequireDefault(require("../index.module.scss"));
 var _jsxRuntime = require("react/jsx-runtime");
@@ -32,6 +33,8 @@ const Gauge = props => {
   } = series;
   const chartRef = (0, _react.useRef)(null);
   const chartInstanceRef = (0, _react.useRef)(null);
+  // Defers `echarts.init` until the container has a box — see the hook for why
+  const containerReady = (0, _useContainerReady.default)(chartRef);
   const resizeObserverRef = (0, _react.useRef)(null);
 
   // Cache the chart option with useMemo
@@ -92,12 +95,16 @@ const Gauge = props => {
 
   // Callback for 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
+    // the laid-out canvas away and it has to be rebuilt when the tab comes back
+    const el = chartRef.current;
+    if (!el || el.clientWidth === 0 || el.clientHeight === 0) return;
     chartInstanceRef.current?.resize();
   }, []);
 
   // Initialize the chart
   (0, _react.useEffect)(() => {
-    if (!chartRef.current) return;
+    if (!chartRef.current || !containerReady) return;
 
     // Initialize or reuse the existing instance
     let chart = chartInstanceRef.current;
@@ -122,7 +129,7 @@ const Gauge = props => {
     return () => {
       window.removeEventListener("resize", handleResize);
     };
-  }, [chartOption, handleResize]);
+  }, [chartOption, handleResize, containerReady]);
 
   // Clean up resources when the component unmounts
   (0, _react.useEffect)(() => {

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

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var _react = _interopRequireWildcard(require("react"));
+var _useContainerReady = _interopRequireDefault(require("../_hooks/useContainerReady"));
 var _indexModule = _interopRequireDefault(require("../index.module.scss"));
 var echarts = _interopRequireWildcard(require("echarts"));
 var _heatmap = require("../_utils/heatmap");
@@ -37,6 +38,8 @@ const Heatmap = props => {
   } = props;
   const chartRef = (0, _react.useRef)(null);
   const chartInstanceRef = (0, _react.useRef)(null);
+  // Defers `echarts.init` until the container has a box — see the hook for why
+  const containerReady = (0, _useContainerReady.default)(chartRef);
   const resizeObserverRef = (0, _react.useRef)(null);
   // echarts options are plain JS and cannot read the `--vita-*` variables, so the axis and legend
   // colours have to be resolved against the active appearance here
@@ -182,12 +185,16 @@ const Heatmap = props => {
 
   // Callback for 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
+    // the laid-out canvas away and it has to be rebuilt when the tab comes back
+    const el = chartRef.current;
+    if (!el || el.clientWidth === 0 || el.clientHeight === 0) return;
     chartInstanceRef.current?.resize();
   }, []);
 
   // Initialize the chart
   (0, _react.useEffect)(() => {
-    if (!chartRef.current) return;
+    if (!chartRef.current || !containerReady) return;
 
     // Initialize or reuse the existing instance
     let chart = chartInstanceRef.current;
@@ -222,7 +229,7 @@ const Heatmap = props => {
         chartInstanceRef.current?.off("click", onClick);
       }
     };
-  }, [chartOption, handleResize, onChart, onClick]);
+  }, [chartOption, handleResize, onChart, onClick, containerReady]);
 
   // Clean up resources when the component unmounts
   (0, _react.useEffect)(() => {

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

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var echarts = _interopRequireWildcard(require("echarts"));
+var _useContainerReady = _interopRequireDefault(require("../_hooks/useContainerReady"));
 var _react = _interopRequireWildcard(require("react"));
 var _indexModule = _interopRequireDefault(require("../index.module.scss"));
 var _autoScrollLegend = require("../_utils/autoScrollLegend");
@@ -45,6 +46,8 @@ const ChartLine = props => {
   } = props;
   const chartRef = (0, _react.useRef)(null);
   const chartInstanceRef = (0, _react.useRef)(null);
+  // Defers `echarts.init` until the container has a box — see the hook for why
+  const containerReady = (0, _useContainerReady.default)(chartRef);
   const resizeObserverRef = (0, _react.useRef)(null);
   const prevXAxisKeyRef = (0, _react.useRef)(null);
   const legendScrollRef = (0, _react.useRef)(null);
@@ -189,12 +192,16 @@ const ChartLine = props => {
 
   // Callback for 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
+    // the laid-out canvas away and it has to be rebuilt when the tab comes back
+    const el = chartRef.current;
+    if (!el || el.clientWidth === 0 || el.clientHeight === 0) return;
     chartInstanceRef.current?.resize();
   }, []);
 
   // Initialize the chart
   (0, _react.useEffect)(() => {
-    if (!chartRef.current) return;
+    if (!chartRef.current || !containerReady) return;
 
     // Initialize or reuse the existing instance
     let chart = chartInstanceRef.current;
@@ -324,7 +331,7 @@ const ChartLine = props => {
     };
   }, [chartOption, handleResize, onClick, onLegendSelectChanged, onDataZoomWindowChanged, xAxisData, enableLegendAutoScroll, legendVisibleCount, legendScrollInterval,
   // 图例是否接管滚轮由它推导，漏了会拿到过期的滚动配置
-  normalizedScroll]);
+  normalizedScroll, containerReady]);
 
   // Handle auto play
   (0, _react.useEffect)(() => {

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

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var echarts = _interopRequireWildcard(require("echarts"));
+var _useContainerReady = _interopRequireDefault(require("../../_hooks/useContainerReady"));
 require("echarts-gl");
 var _react = _interopRequireWildcard(require("react"));
 var _hooks = require("./_hooks");
@@ -41,6 +42,8 @@ const ChartPie3D = props => {
   } = props;
   const chartRef = (0, _react.useRef)(null);
   const chartInstanceRef = (0, _react.useRef)(null);
+  // Defers `echarts.init` until the container has a box — see the hook for why
+  const containerReady = (0, _useContainerReady.default)(chartRef);
   const resizeObserverRef = (0, _react.useRef)(null);
   const hoveredIndexRef = (0, _react.useRef)("");
   const optionRef = (0, _react.useRef)(null);
@@ -62,6 +65,10 @@ const ChartPie3D = props => {
     });
   }, [pieData, internalDiameterRatio, tooltip, alpha, beta, autoRotate, distance, coreOption, minHeight, maxHeight, yOffset, label, enableMouseControl]);
   const handleResize = (0, _react.useCallback)(() => {
+    // A keep-alive tab losing focus fires the observer with a 0×0 box; resizing to that throws
+    // the laid-out canvas away and it has to be rebuilt when the tab comes back
+    const el = chartRef.current;
+    if (!el || el.clientWidth === 0 || el.clientHeight === 0) return;
     chartInstanceRef.current?.resize();
   }, []);
   const handleMouseOver = (0, _hooks.useMouseOverHandler)(optionRef, chartInstanceRef, hoveredIndexRef, {
@@ -78,7 +85,7 @@ const ChartPie3D = props => {
     autoRotate
   });
   (0, _react.useEffect)(() => {
-    if (!chartRef.current) return;
+    if (!chartRef.current || !containerReady) return;
     let chart = chartInstanceRef.current;
     if (!chart) {
       chart = echarts.init(chartRef.current);
@@ -107,7 +114,7 @@ const ChartPie3D = props => {
         }
       }
     };
-  }, [chartOption, handleResize, handleMouseOver, handleGlobalOut, onChart, onClick]);
+  }, [chartOption, handleResize, handleMouseOver, handleGlobalOut, onChart, onClick, containerReady]);
   (0, _react.useEffect)(() => {
     return () => {
       if (resizeObserverRef.current) {

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

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var echarts = _interopRequireWildcard(require("echarts"));
+var _useContainerReady = _interopRequireDefault(require("../_hooks/useContainerReady"));
 var _react = _interopRequireWildcard(require("react"));
 var _chartUtils = require("../chartUtils");
 var _indexModule = _interopRequireDefault(require("../index.module.scss"));
@@ -38,6 +39,8 @@ const ChartPie = props => {
   } = props;
   const chartRef = (0, _react.useRef)(null);
   const chartInstanceRef = (0, _react.useRef)(null);
+  // Defers `echarts.init` until the container has a box — see the hook for why
+  const containerReady = (0, _useContainerReady.default)(chartRef);
   const resizeObserverRef = (0, _react.useRef)(null);
   const legendScrollRef = (0, _react.useRef)(null);
 
@@ -191,12 +194,16 @@ const ChartPie = props => {
 
   // Callback for 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
+    // the laid-out canvas away and it has to be rebuilt when the tab comes back
+    const el = chartRef.current;
+    if (!el || el.clientWidth === 0 || el.clientHeight === 0) return;
     chartInstanceRef.current?.resize();
   }, []);
 
   // Initialize the chart
   (0, _react.useEffect)(() => {
-    if (!chartRef.current) return;
+    if (!chartRef.current || !containerReady) return;
 
     // Initialize or reuse the existing instance
     let chart = chartInstanceRef.current;
@@ -252,7 +259,7 @@ const ChartPie = props => {
         legendScrollRef.current = null;
       }
     };
-  }, [chartOption, handleResize, onChart, onClick, enableLegendAutoScroll, seriesData, legendVisibleCount, legendScrollInterval]);
+  }, [chartOption, handleResize, onChart, onClick, enableLegendAutoScroll, seriesData, legendVisibleCount, legendScrollInterval, containerReady]);
 
   // Clean up resources when the component unmounts
   (0, _react.useEffect)(() => {

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

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var echarts = _interopRequireWildcard(require("echarts"));
+var _useContainerReady = _interopRequireDefault(require("../_hooks/useContainerReady"));
 var _react = _interopRequireWildcard(require("react"));
 var _indexModule = _interopRequireDefault(require("../index.module.scss"));
 var _jsxRuntime = require("react/jsx-runtime");
@@ -30,6 +31,8 @@ const Polar = props => {
   } = props;
   const chartRef = (0, _react.useRef)(null);
   const chartInstanceRef = (0, _react.useRef)(null);
+  // Defers `echarts.init` until the container has a box — see the hook for why
+  const containerReady = (0, _useContainerReady.default)(chartRef);
   const resizeObserverRef = (0, _react.useRef)(null);
 
   // Cache the chart option with useMemo
@@ -144,12 +147,16 @@ const Polar = props => {
 
   // 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
+    // the laid-out canvas away and it has to be rebuilt when the tab comes back
+    const el = chartRef.current;
+    if (!el || el.clientWidth === 0 || el.clientHeight === 0) return;
     chartInstanceRef.current?.resize();
   }, []);
 
   // Initialize the chart
   (0, _react.useEffect)(() => {
-    if (!chartRef.current) return;
+    if (!chartRef.current || !containerReady) return;
 
     // Initialize a new instance or reuse the existing one
     let chart = chartInstanceRef.current;
@@ -174,7 +181,7 @@ const Polar = props => {
     return () => {
       window.removeEventListener("resize", handleResize);
     };
-  }, [chartOption, handleResize]);
+  }, [chartOption, handleResize, containerReady]);
 
   // Clean up resources on unmount
   (0, _react.useEffect)(() => {

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

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var echarts = _interopRequireWildcard(require("echarts"));
+var _useContainerReady = _interopRequireDefault(require("../_hooks/useContainerReady"));
 var _react = _interopRequireWildcard(require("react"));
 var _indexModule = _interopRequireDefault(require("../index.module.scss"));
 var _jsxRuntime = require("react/jsx-runtime");
@@ -33,6 +34,8 @@ const Radar = props => {
   } = props;
   const chartRef = (0, _react.useRef)(null);
   const chartInstanceRef = (0, _react.useRef)(null);
+  // Defers `echarts.init` until the container has a box — see the hook for why
+  const containerReady = (0, _useContainerReady.default)(chartRef);
   const resizeObserverRef = (0, _react.useRef)(null);
   const hoveredIndicatorRef = (0, _react.useRef)(-1);
   const singleIndicatorEnabled = Boolean(singleIndicatorTooltipProp) && singleIndicatorMode !== undefined;
@@ -144,10 +147,14 @@ const Radar = props => {
     return option;
   }, [indicators, data, color, name, radar, series, coreOption, singleIndicatorEnabled, singleIndicatorFormatter, singleIndicatorRegion]);
   const handleResize = (0, _react.useCallback)(() => {
+    // A keep-alive tab losing focus fires the observer with a 0×0 box; resizing to that throws
+    // the laid-out canvas away and it has to be rebuilt when the tab comes back
+    const el = chartRef.current;
+    if (!el || el.clientWidth === 0 || el.clientHeight === 0) return;
     chartInstanceRef.current?.resize();
   }, []);
   (0, _react.useEffect)(() => {
-    if (!chartRef.current) return;
+    if (!chartRef.current || !containerReady) return;
     let chart = chartInstanceRef.current;
     if (!chart) {
       chart = echarts.init(chartRef.current);
@@ -263,7 +270,7 @@ const Radar = props => {
         }
       }
     };
-  }, [chartOption, handleResize, singleIndicatorEnabled, singleIndicatorRegion, singleIndicatorHighlight, singleIndicatorHoverFill, color]);
+  }, [chartOption, handleResize, singleIndicatorEnabled, singleIndicatorRegion, singleIndicatorHighlight, singleIndicatorHoverFill, color, containerReady]);
   (0, _react.useEffect)(() => {
     return () => {
       if (resizeObserverRef.current) {

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

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var _react = _interopRequireWildcard(require("react"));
+var _useContainerReady = _interopRequireDefault(require("../_hooks/useContainerReady"));
 var _indexModule = _interopRequireDefault(require("../index.module.scss"));
 var echarts = _interopRequireWildcard(require("echarts"));
 var _jsxRuntime = require("react/jsx-runtime");
@@ -22,6 +23,8 @@ const Sankey = props => {
   } = props;
   const chartRef = (0, _react.useRef)(null);
   const chartInstanceRef = (0, _react.useRef)(null);
+  // Defers `echarts.init` until the container has a box — see the hook for why
+  const containerReady = (0, _useContainerReady.default)(chartRef);
   const resizeObserverRef = (0, _react.useRef)(null);
 
   // Cache the chart option with useMemo
@@ -103,12 +106,16 @@ const Sankey = props => {
 
   // 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
+    // the laid-out canvas away and it has to be rebuilt when the tab comes back
+    const el = chartRef.current;
+    if (!el || el.clientWidth === 0 || el.clientHeight === 0) return;
     chartInstanceRef.current?.resize();
   }, []);
 
   // Initialize the chart
   (0, _react.useEffect)(() => {
-    if (!chartRef.current) return;
+    if (!chartRef.current || !containerReady) return;
 
     // Initialize a new instance or reuse the existing one
     let chart = chartInstanceRef.current;
@@ -142,7 +149,7 @@ const Sankey = props => {
     return () => {
       window.removeEventListener("resize", handleResize);
     };
-  }, [chartOption, handleResize, getImage]);
+  }, [chartOption, handleResize, getImage, containerReady]);
 
   // Clean up resources on unmount
   (0, _react.useEffect)(() => {

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

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var _react = _interopRequireWildcard(require("react"));
+var _useContainerReady = _interopRequireDefault(require("../_hooks/useContainerReady"));
 var _indexModule = _interopRequireDefault(require("../index.module.scss"));
 var echarts = _interopRequireWildcard(require("echarts"));
 var _hsuUtils = require("hsu-utils");
@@ -23,6 +24,8 @@ const Tree = props => {
   } = props;
   const chartRef = (0, _react.useRef)(null);
   const chartInstanceRef = (0, _react.useRef)(null);
+  // Defers `echarts.init` until the container has a box — see the hook for why
+  const containerReady = (0, _useContainerReady.default)(chartRef);
   const resizeObserverRef = (0, _react.useRef)(null);
 
   // Cache the chart option with useMemo
@@ -43,12 +46,16 @@ const Tree = props => {
 
   // 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
+    // the laid-out canvas away and it has to be rebuilt when the tab comes back
+    const el = chartRef.current;
+    if (!el || el.clientWidth === 0 || el.clientHeight === 0) return;
     chartInstanceRef.current?.resize();
   }, []);
 
   // Initialize the chart
   (0, _react.useEffect)(() => {
-    if (!chartRef.current) return;
+    if (!chartRef.current || !containerReady) return;
 
     // Initialize a new instance or reuse the existing one
     let chart = chartInstanceRef.current;
@@ -82,7 +89,7 @@ const Tree = props => {
     return () => {
       window.removeEventListener("resize", handleResize);
     };
-  }, [chartOption, handleResize, getImage]);
+  }, [chartOption, handleResize, getImage, containerReady]);
 
   // Clean up resources on unmount
   (0, _react.useEffect)(() => {

package/lib/components/Chart/_hooks/useContainerReady.d.ts

@@ -0,0 +1,18 @@
+import { RefObject } from "react";
+/**
+ * Whether the referenced element has a non-zero box yet.
+ *
+ * `echarts.init` on a 0×0 element logs `Can't get DOM width or height` and builds a canvas with no
+ * size, recovering only on the next `resize()`. A chart hits that path whenever it mounts before
+ * layout has given it space — inside a keep-alive tab that is not the active one, a collapsed
+ * panel, a modal that has not opened yet — so consuming apps see the warning for charts that end
+ * up rendering perfectly well.
+ *
+ * Gating `init` on this flag defers it to the first frame the element actually occupies space.
+ *
+ * It **latches**: once measured, the element going back to 0×0 (a keep-alive tab losing focus)
+ * must not read as "not ready" again, or the init effect would tear the chart down and re-create
+ * it on every tab switch.
+ */
+declare const useContainerReady: (ref: RefObject<HTMLElement | null>) => boolean;
+export default useContainerReady;

package/lib/components/Chart/_hooks/useContainerReady.js

@@ -0,0 +1,51 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _react = require("react");
+/**
+ * Whether the referenced element has a non-zero box yet.
+ *
+ * `echarts.init` on a 0×0 element logs `Can't get DOM width or height` and builds a canvas with no
+ * size, recovering only on the next `resize()`. A chart hits that path whenever it mounts before
+ * layout has given it space — inside a keep-alive tab that is not the active one, a collapsed
+ * panel, a modal that has not opened yet — so consuming apps see the warning for charts that end
+ * up rendering perfectly well.
+ *
+ * Gating `init` on this flag defers it to the first frame the element actually occupies space.
+ *
+ * It **latches**: once measured, the element going back to 0×0 (a keep-alive tab losing focus)
+ * must not read as "not ready" again, or the init effect would tear the chart down and re-create
+ * it on every tab switch.
+ */
+const useContainerReady = ref => {
+  const [ready, setReady] = (0, _react.useState)(false);
+  (0, _react.useEffect)(() => {
+    if (ready) return;
+    const el = ref.current;
+    if (!el) return;
+    const measure = () => {
+      const {
+        width,
+        height
+      } = el.getBoundingClientRect();
+      if (width > 0 && height > 0) {
+        setReady(true);
+        return true;
+      }
+      return false;
+    };
+
+    // Already laid out on mount — the common case, and it must not cost an extra frame
+    if (measure()) return;
+    const observer = new ResizeObserver(() => {
+      if (measure()) observer.disconnect();
+    });
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [ready, ref]);
+  return ready;
+};
+var _default = exports.default = useContainerReady;

package/package.json

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

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

@@ -1,4 +1,5 @@
 import * as echarts from "echarts";
+import useContainerReady from "../_hooks/useContainerReady";
 
 import {
   ChartCommonProps,
@@ -72,6 +73,8 @@ const ChartBar: React.FC<ChartBarProps> = (props) => {
   } = props;
   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
+  const containerReady = useContainerReady(chartRef);
   const resizeObserverRef = useRef<ResizeObserver | null>(null);
   const prevXAxisKeyRef = useRef<string | null>(null);
   const legendScrollRef = useRef<ReturnType<typeof autoScrollLegend> | null>(
@@ -269,12 +272,17 @@ const ChartBar: React.FC<ChartBarProps> = (props) => {
 
   // Callback for handling chart resize
   const handleResize = useCallback(() => {
+    // A keep-alive tab losing focus fires the observer with a 0×0 box; resizing to that throws
+    // the laid-out canvas away and it has to be rebuilt when the tab comes back
+    const el = chartRef.current;
+    if (!el || el.clientWidth === 0 || el.clientHeight === 0) return;
+
     chartInstanceRef.current?.resize();
   }, []);
 
   // Initialize the chart
   useEffect(() => {
-    if (!chartRef.current) return;
+    if (!chartRef.current || !containerReady) return;
 
     // Initialize or reuse the existing instance
     let chart = chartInstanceRef.current;
@@ -469,6 +477,7 @@ const ChartBar: React.FC<ChartBarProps> = (props) => {
     legendScrollInterval,
     // 图例是否接管滚轮由它推导，漏了会拿到过期的滚动配置
     normalizedScroll,
+    containerReady,
   ]);
 
   // Handle auto play

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

@@ -1,4 +1,5 @@
 import React, { useCallback, useEffect, useMemo, useRef } from "react";
+import useContainerReady from "../_hooks/useContainerReady";
 import styles from "../index.module.scss";
 import { ChartCommonProps, ChartOptionType, ChartsOption } from "..";
 import * as echarts from "echarts";
@@ -7,6 +8,8 @@ const Common: React.FC<ChartCommonProps> = (props) => {
   const { className, style, onChart, ...coreOption } = props;
   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
+  const containerReady = useContainerReady(chartRef);
   const resizeObserverRef = useRef<ResizeObserver | null>(null);
 
   // Cache the chart configuration with useMemo
@@ -20,12 +23,17 @@ const Common: React.FC<ChartCommonProps> = (props) => {
 
   // Callback that handles chart resize
   const handleResize = useCallback(() => {
+    // A keep-alive tab losing focus fires the observer with a 0×0 box; resizing to that throws
+    // the laid-out canvas away and it has to be rebuilt when the tab comes back
+    const el = chartRef.current;
+    if (!el || el.clientWidth === 0 || el.clientHeight === 0) return;
+
     chartInstanceRef.current?.resize();
   }, []);
 
   // Initialize the chart
   useEffect(() => {
-    if (!chartRef.current) return;
+    if (!chartRef.current || !containerReady) return;
 
     // Initialize or reuse an existing instance
     let chart = chartInstanceRef.current;
@@ -53,7 +61,9 @@ const Common: React.FC<ChartCommonProps> = (props) => {
     return () => {
       window.removeEventListener("resize", handleResize);
     };
-  }, [chartOption, handleResize, onChart]);
+  }, [chartOption, handleResize, onChart,
+    containerReady,
+  ]);
 
   // Clean up resources on component unmount
   useEffect(() => {

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

@@ -1,4 +1,5 @@
 import * as echarts from "echarts";
+import useContainerReady from "../_hooks/useContainerReady";
 
 import {
   ChartCommonProps,
@@ -31,6 +32,8 @@ const Gauge: React.FC<ChartGaugeProps> = (props) => {
   } = series as echarts.GaugeSeriesOption;
   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
+  const containerReady = useContainerReady(chartRef);
   const resizeObserverRef = useRef<ResizeObserver | null>(null);
 
   // Cache the chart option with useMemo
@@ -104,12 +107,17 @@ const Gauge: React.FC<ChartGaugeProps> = (props) => {
 
   // Callback for handling chart resize
   const handleResize = useCallback(() => {
+    // A keep-alive tab losing focus fires the observer with a 0×0 box; resizing to that throws
+    // the laid-out canvas away and it has to be rebuilt when the tab comes back
+    const el = chartRef.current;
+    if (!el || el.clientWidth === 0 || el.clientHeight === 0) return;
+
     chartInstanceRef.current?.resize();
   }, []);
 
   // Initialize the chart
   useEffect(() => {
-    if (!chartRef.current) return;
+    if (!chartRef.current || !containerReady) return;
 
     // Initialize or reuse the existing instance
     let chart = chartInstanceRef.current;
@@ -134,7 +142,9 @@ const Gauge: React.FC<ChartGaugeProps> = (props) => {
     return () => {
       window.removeEventListener("resize", handleResize);
     };
-  }, [chartOption, handleResize]);
+  }, [chartOption, handleResize,
+    containerReady,
+  ]);
 
   // Clean up resources when the component unmounts
   useEffect(() => {