@hsu-react/ui 2.5.3 → 2.5.4

package/es/components/Input/TextArea/index.js

@@ -17,6 +17,7 @@ import AntdTextArea from "antd/es/input/TextArea";
 import React, { useEffect, useRef, useState } from "react";
 import classNames from "classnames";
 import styles from "./index.module.scss";
+import { useLatestRef } from "../../../hooks/useLatestRef";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { jsxs as _jsxs } from "react/jsx-runtime";
 var TextArea = function TextArea(props) {
@@ -40,56 +41,74 @@ var TextArea = function TextArea(props) {
     autoSize = props.autoSize,
     style = props.style,
     inputConfig = _objectWithoutProperties(props, _excluded);
+  var ref = useRef(null);
   var _useState = useState(false),
     _useState2 = _slicedToArray(_useState, 2),
-    isComposing = _useState2[0],
-    setComposing = _useState2[1];
-  var ref = useRef(null);
-  var _useState3 = useState(false),
-    _useState4 = _slicedToArray(_useState3, 2),
-    focused = _useState4[0],
-    setFocused = _useState4[1];
+    focused = _useState2[0],
+    setFocused = _useState2[1];
 
   // On initialization, prefer value, then fall back to defaultValue
   var initialValue = value !== undefined ? (_value$toString = value === null || value === void 0 ? void 0 : value.toString()) !== null && _value$toString !== void 0 ? _value$toString : "" : defaultValue !== undefined ? (_defaultValue$toStrin = defaultValue === null || defaultValue === void 0 ? void 0 : defaultValue.toString()) !== null && _defaultValue$toStrin !== void 0 ? _defaultValue$toStrin : "" : "";
-  var _useState5 = useState(initialValue),
+  var _useState3 = useState(initialValue),
+    _useState4 = _slicedToArray(_useState3, 2),
+    _value = _useState4[0],
+    setValue = _useState4[1];
+  var _useState5 = useState(false),
     _useState6 = _slicedToArray(_useState5, 2),
-    _value = _useState6[0],
-    setValue = _useState6[1];
-  var _useState7 = useState(initialValue),
-    _useState8 = _slicedToArray(_useState7, 2),
-    lastValue = _useState8[0],
-    setLastValue = _useState8[1];
-  var _useState9 = useState(false),
-    _useState10 = _slicedToArray(_useState9, 2),
-    hasError = _useState10[0],
-    setHasError = _useState10[1];
+    hasError = _useState6[0],
+    setHasError = _useState6[1];
   var prevValueRef = useRef(undefined);
-  useEffect(function () {
-    if (!isComposing && _value !== lastValue) {
-      var trimmedValue = _value.trim();
-      var finalValue = trimmedValue === "" ? "" : _value;
-      setLastValue(finalValue);
-      onChange === null || onChange === void 0 || onChange(finalValue);
-    }
-  }, [isComposing, onChange, _value, lastValue]);
+  var getRefRef = useLatestRef(getRef);
+
+  // 输入法组字期间不往外通知。放 ref 不放 state：它只影响「要不要发通知」，
+  // 不参与渲染，而且必须在同一次事件里立刻生效
+  var composingRef = useRef(false);
+  // 最近一次通知出去的原文。只用来去掉 compositionend 与 input 两个事件的重复通知
+  var notifiedRef = useRef(initialValue);
+
+  /**
+   * `onChange` 是「用户改了输入」这个**事件**的通知，不是从 state 推导出来的结果，
+   * 所以它在事件处理里发，不在 effect 里发。
+   *
+   * 早先是一个 effect 在发：依赖数组里放着 `onChange`，effect 体内又调它，
+   * 还用一个 `lastValue` state 记「这个值通知过没有」。两处都是错的——
+   * 1. 消费方传内联箭头（`onChange={(v) => setX(v)}`，React 里最常见的写法）时
+   *    每次渲染都是新引用，effect 每次渲染都重跑；
+   * 2. 「通知过没有」的记账放在 React state 里就**不可靠**：父级用 MobX /
+   *    `useSyncExternalStore` 这类外部 store 回写 `value` 时，React 会以更高的
+   *    同步优先级重渲一次，effect 里排的那次 `setLastValue` 会被这一趟**跳过**，
+   *    于是 effect 读到过期的记账、判定「还没通知」，再发一次 → 父级再回写 →
+   *    死循环，React 抛 `Maximum update depth exceeded`，输入框被上层
+   *    ErrorBoundary 整块摘掉。
+   *
+   * 现在 `onChange` 的引用稳不稳定完全不影响正确性：永远调到最新的那个回调，
+   * 且只在真的有新文本时调一次。
+   */
+  var notify = function notify(next) {
+    if (next === notifiedRef.current) return;
+    notifiedRef.current = next;
+    // 全是空白等同于空：外部拿到的是 ""，但输入框里用户敲的空格照旧留着
+    onChange === null || onChange === void 0 || onChange(next.trim() === "" ? "" : next);
+  };
   useEffect(function () {
     // Update internal state only when the external value prop actually changes
     if (prevValueRef.current !== value) {
+      var _value$toString2;
       prevValueRef.current = value;
-      if (value !== undefined) {
-        setValue(value === null || value === void 0 ? void 0 : value.toString());
-        setLastValue(value === null || value === void 0 ? void 0 : value.toString());
-      } else {
-        // Clear only on initialization or when explicitly set to undefined externally
-        setValue("");
-        setLastValue("");
-      }
+
+      // 外部把值改了，之前通知过什么就不作数了，重新以外部值为准
+      var next = value !== undefined ? (_value$toString2 = value === null || value === void 0 ? void 0 : value.toString()) !== null && _value$toString2 !== void 0 ? _value$toString2 : "" : "";
+      notifiedRef.current = next;
+      setValue(next);
     }
   }, [value]);
+
+  // 只在挂载时把 ref 交出去。`getRef` 进依赖数组同样会被内联箭头带着每次渲染重跑，
+  // 消费方在里面 setState 就是一个死循环
   useEffect(function () {
-    getRef === null || getRef === void 0 || getRef(ref.current);
-  }, [getRef]);
+    var _getRefRef$current;
+    (_getRefRef$current = getRefRef.current) === null || _getRefRef$current === void 0 || _getRefRef$current.call(getRefRef, ref.current);
+  }, [getRefRef]);
   useEffect(function () {
     var _ref$current2;
     // Use a MutationObserver to watch for error state changes
@@ -124,19 +143,22 @@ var TextArea = function TextArea(props) {
     children: [prefix, /*#__PURE__*/_jsx(AntdTextArea, _objectSpread({
       ref: ref,
       onCompositionStart: function onCompositionStart() {
-        return setComposing(true);
+        composingRef.current = true;
       },
-      onCompositionEnd: function onCompositionEnd() {
-        setTimeout(function () {
-          setComposing(false);
-        }, 1);
+      onCompositionEnd: function onCompositionEnd(e) {
+        composingRef.current = false;
+        // 组完字的那一下自己发通知。浏览器之间 compositionend 与 input 的先后
+        // 不一致，`notify` 里按原文去重，两种顺序都只会发出一次
+        notify(e.currentTarget.value);
       },
       value: _value,
       autoSize: disabled && text ? autoSize || {
         minRows: 1
       } : autoSize,
       onChange: function onChange(e) {
-        setValue(e.target.value);
+        var next = e.target.value;
+        setValue(next);
+        if (!composingRef.current) notify(next);
       },
       onFocus: function onFocus(e) {
         setFocused(true);

package/es/components/Input/index.js

@@ -22,7 +22,7 @@ import TextArea from "./TextArea";
 import classNames from "classnames";
 import styles from "./index.module.scss";
 import RangeInput from "./Range";
-import { useDebounceEffect } from "ahooks";
+import { useLatestRef } from "../../hooks/useLatestRef";
 import { jsx as _jsx } from "react/jsx-runtime";
 var Input = function Input(props) {
   var onChange = props.onChange,
@@ -39,11 +39,11 @@ var Input = function Input(props) {
     tooltip = props.tooltip,
     escapeCharacters = props.escapeCharacters,
     inputConfig = _objectWithoutProperties(props, _excluded);
-  var _useState = useState(false),
-    _useState2 = _slicedToArray(_useState, 2),
-    isComposing = _useState2[0],
-    setComposing = _useState2[1];
   var ref = useRef(null);
+  var getRefRef = useLatestRef(getRef);
+  // 输入法组字期间不往外通知。放 ref 不放 state：它只决定「要不要发通知」，
+  // 不参与渲染，而且必须在同一次事件里立刻生效
+  var composingRef = useRef(false);
 
   // Handle escaping: if the value contains characters listed in escapeCharacters, prefix them with an escape
   var escapeValue = useCallback(function (val) {
@@ -112,27 +112,27 @@ var Input = function Input(props) {
     return unescapeValue(rawValue);
   };
   var initialValue = getInitialValue();
-  var _useState3 = useState(initialValue),
-    _useState4 = _slicedToArray(_useState3, 2),
-    _value = _useState4[0],
-    setValue = _useState4[1];
-  var _useState5 = useState(initialValue),
-    _useState6 = _slicedToArray(_useState5, 2),
-    lastValue = _useState6[0],
-    setLastValue = _useState6[1];
+  var _useState = useState(initialValue),
+    _useState2 = _slicedToArray(_useState, 2),
+    _value = _useState2[0],
+    setValue = _useState2[1];
   var prevValueRef = useRef(undefined);
-  useDebounceEffect(function () {
-    if (!isComposing && _value !== lastValue) {
-      var trimmedValue = _value.trim();
-      var finalValue = trimmedValue === "" ? "" : _value;
-      setLastValue(finalValue);
-      // If escapeCharacters is set and the value matches, return the escaped value
-      var escapedValue = escapeValue(finalValue);
-      onChange === null || onChange === void 0 || onChange(escapedValue);
-    }
-  }, [_value, isComposing, lastValue, onChange, escapeValue], {
-    wait: 10
-  });
+  // 最近一次通知出去的原文（未转义）。只用来去掉 compositionend 与 input
+  // 两个事件的重复通知
+  var notifiedRef = useRef(initialValue);
+
+  /**
+   * `onChange` 是「用户改了输入」这个**事件**的通知，不是从 state 推导出来的结果，
+   * 所以在事件处理里发，不在 effect 里发。详见 `TextArea/index.tsx` 里那段说明——
+   * 旧写法（依赖数组里放 `onChange`、体内又调它、用 state 记「通知过没有」）
+   * 会让传内联箭头的消费方死循环。
+   */
+  var notify = function notify(next) {
+    if (next === notifiedRef.current) return;
+    notifiedRef.current = next;
+    // 全是空白等同于空；escapeCharacters 命中时对外给转义后的值
+    onChange === null || onChange === void 0 || onChange(escapeValue(next.trim() === "" ? "" : next));
+  };
   useEffect(function () {
     // Update internal state only when the external value prop actually changes
     if (prevValueRef.current !== value) {
@@ -141,18 +141,22 @@ var Input = function Input(props) {
         var rawValue = typeof value === "number" ? "".concat(value) : value === null || value === void 0 ? void 0 : value.toString();
         // Unescape before displaying
         var newValue = unescapeValue(rawValue);
+        // 外部把值改了，之前通知过什么就不作数了，重新以外部值为准
+        notifiedRef.current = newValue;
         setValue(newValue);
-        setLastValue(newValue);
       } else {
         // Clear only on initialization or when explicitly set to undefined externally
+        notifiedRef.current = "";
         setValue("");
-        setLastValue("");
       }
     }
   }, [value, unescapeValue]);
+
+  // 只在挂载时把 ref 交出去。`getRef` 进依赖数组同样会被内联箭头带着每次渲染重跑
   useEffect(function () {
-    getRef === null || getRef === void 0 || getRef(ref.current);
-  }, [getRef]);
+    var _getRefRef$current;
+    (_getRefRef$current = getRefRef.current) === null || _getRefRef$current === void 0 || _getRefRef$current.call(getRefRef, ref.current);
+  }, [getRefRef]);
   return /*#__PURE__*/_jsx(Tooltip, _objectSpread(_objectSpread({
     placement: "topLeft"
   }, tooltip), {}, {
@@ -161,12 +165,13 @@ var Input = function Input(props) {
       disabled: disabled,
       placeholder: disabled ? "" : placeholder,
       onCompositionStart: function onCompositionStart() {
-        return setComposing(true);
+        composingRef.current = true;
       },
-      onCompositionEnd: function onCompositionEnd() {
-        setTimeout(function () {
-          setComposing(false);
-        }, 1);
+      onCompositionEnd: function onCompositionEnd(e) {
+        composingRef.current = false;
+        // 组完字的那一下自己发通知。浏览器之间 compositionend 与 input 的先后
+        // 不一致，`notify` 里按原文去重，两种顺序都只会发出一次
+        notify(unescapeValue(e.currentTarget.value));
       },
       value: _value,
       onChange: function onChange(e) {
@@ -174,6 +179,7 @@ var Input = function Input(props) {
         var inputValue = e.target.value;
         var unescapedInput = unescapeValue(inputValue);
         setValue(unescapedInput);
+        if (!composingRef.current) notify(unescapedInput);
       },
       className: classNames(styles.antdInput, className),
       type: type,

package/es/components/Select/_hooks/useSelectInputOptions.js

@@ -5,6 +5,7 @@ function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len
 function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (null != t) { var e, n, i, u, a = [], f = !0, o = !1; try { if (i = (t = t.call(r)).next, 0 === l) { if (Object(t) !== t) return; f = !1; } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0); } catch (r) { o = !0, n = r; } finally { try { if (!f && null != t.return && (u = t.return(), Object(u) !== u)) return; } finally { if (o) throw n; } } return a; } }
 function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
 import { useEffect, useState } from "react";
+import { useLatestRef } from "../../../hooks/useLatestRef";
 /**
  * Manage input options (when there are no matching options)
  */
@@ -18,11 +19,16 @@ export function useSelectInputOptions(_ref) {
     _useState2 = _slicedToArray(_useState, 2),
     inputOptions = _useState2[0],
     setInputOptions = _useState2[1];
+  var onSearchRef = useLatestRef(onSearch);
+
+  // 回调 prop 不进依赖数组：消费方传内联箭头时每次渲染都是新引用，effect 会跟着
+  // 重跑并再调一次回调 —— 回调里 setState 就是死循环（详见 Input/TextArea 的说明）
   useEffect(function () {
     if (!isComposing) {
-      onSearch === null || onSearch === void 0 || onSearch(searchValue);
+      var _onSearchRef$current;
+      (_onSearchRef$current = onSearchRef.current) === null || _onSearchRef$current === void 0 || _onSearchRef$current.call(onSearchRef, searchValue);
     }
-  }, [inputOptions, isComposing, onChange, onSearch, optionsLength, searchValue]);
+  }, [inputOptions, isComposing, onSearchRef, optionsLength, searchValue]);
   return {
     inputOptions: inputOptions,
     setInputOptions: setInputOptions

package/es/components/Slider/index.js

@@ -14,7 +14,7 @@ function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
 function _objectWithoutProperties(source, excluded) { if (source == null) return {}; var target = _objectWithoutPropertiesLoose(source, excluded); var key, i; if (Object.getOwnPropertySymbols) { var sourceSymbolKeys = Object.getOwnPropertySymbols(source); for (i = 0; i < sourceSymbolKeys.length; i++) { key = sourceSymbolKeys[i]; if (excluded.indexOf(key) >= 0) continue; if (!Object.prototype.propertyIsEnumerable.call(source, key)) continue; target[key] = source[key]; } } return target; }
 function _objectWithoutPropertiesLoose(source, excluded) { if (source == null) return {}; var target = {}; var sourceKeys = Object.keys(source); var key, i; for (i = 0; i < sourceKeys.length; i++) { key = sourceKeys[i]; if (excluded.indexOf(key) >= 0) continue; target[key] = source[key]; } return target; }
 import { Slider as AntdSlider } from "antd";
-import React, { useEffect, useState } from "react";
+import React, { useEffect, useRef, useState } from "react";
 import classNames from "classnames";
 import styles from "./index.module.scss";
 import { jsx as _jsx } from "react/jsx-runtime";
@@ -29,28 +29,37 @@ var Slider = function Slider(props) {
     _useState2 = _slicedToArray(_useState, 2),
     _value = _useState2[0],
     setValue = _useState2[1];
-  var _useState3 = useState(value),
-    _useState4 = _slicedToArray(_useState3, 2),
-    lastValue = _useState4[0],
-    setLastValue = _useState4[1];
+  // 最近一次通知出去的值，代替原来那个用 state 记账的写法
+  var notifiedRef = useRef(value);
+
+  /**
+   * `onChange` 是「用户拖了滑块」这个**事件**的通知，不是从 state 推导出来的结果，
+   * 所以在事件处理里发，不在 effect 里发。详见 `Input/TextArea/index.tsx` 里那段
+   * 说明——旧写法（依赖数组里放 `onChange`、体内又调它、用 state 记「通知过没有」）
+   * 会让传内联箭头的消费方死循环。
+   */
+  var handleChange = function handleChange(next) {
+    setValue(next);
+    if (next === notifiedRef.current) return;
+    notifiedRef.current = next;
+    onChange === null || onChange === void 0 || onChange(next);
+  };
+
+  // 外部值（`value` / `topValue`）变了才回写，不跟着通知走
   useEffect(function () {
-    if (_value !== lastValue) {
-      setLastValue(_value);
-      onChange === null || onChange === void 0 || onChange(_value);
+    var next = topValue || value;
+    if (next !== notifiedRef.current) {
+      notifiedRef.current = next;
+      setValue(next);
     }
-  }, [lastValue, onChange, _value]);
-  useEffect(function () {
-    if ((topValue || value) !== lastValue) {
-      setValue(topValue || value);
-    }
-  }, [lastValue, topValue, value]);
+  }, [topValue, value]);
   return /*#__PURE__*/_jsx(AntdSlider, _objectSpread({
     className: classNames([styles.slider, className]),
     tooltip: {
       open: false
     },
     value: _value,
-    onChange: setValue
+    onChange: handleChange
   }, sliderConfig));
 };
 export default Slider;

package/es/components/Upload/_hooks/useUploadFileList.js

@@ -7,6 +7,7 @@ function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
 import { useEffect, useState } from "react";
 import { deepCopy, Equal } from "hsu-utils";
 import { extractFileUrl } from "../_utils";
+import { useLatestRef } from "../../../hooks/useLatestRef";
 /**
  * Manage the upload file list state
  */
@@ -22,6 +23,10 @@ export function useUploadFileList(_ref) {
     _useState4 = _slicedToArray(_useState3, 2),
     lastFileList = _useState4[0],
     setLastFileList = _useState4[1];
+  var onChangeRef = useLatestRef(onChange);
+
+  // 回调 prop 不进依赖数组：消费方传内联箭头时每次渲染都是新引用，effect 会跟着
+  // 重跑并再调一次回调 —— 回调里 setState 就是死循环（详见 Input/TextArea 的说明）
   useEffect(function () {
     if (rmFile) {
       var file = _fileList.find(function (item) {
@@ -33,14 +38,15 @@ export function useUploadFileList(_ref) {
       if (file) {
         setFilelist(filteredList);
         setTimeout(function () {
-          onChange === null || onChange === void 0 || onChange({
+          var _onChangeRef$current;
+          (_onChangeRef$current = onChangeRef.current) === null || _onChangeRef$current === void 0 || _onChangeRef$current.call(onChangeRef, {
             file: file,
             fileList: filteredList
           });
         }, 100);
       }
     }
-  }, [_fileList, onChange, rmFile]);
+  }, [_fileList, onChangeRef, rmFile]);
   useEffect(function () {
     if (!Equal.ObjEqual(fileList !== null && fileList !== void 0 ? fileList : [], lastFileList)) {
       if (fileList !== null && fileList !== void 0 && fileList.length) {

package/es/components/Upload/_hooks/useUploadOperations.js

@@ -6,6 +6,7 @@ function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" !=
 function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
 import { useEffect, useRef, useState } from "react";
 import { deepCopy, Equal } from "hsu-utils";
+import { useLatestRef } from "../../../hooks/useLatestRef";
 /**
  * Manage upload and download operations
  */
@@ -27,6 +28,7 @@ export function useUploadOperations(_ref) {
     downloading: {},
     uploadingList: {}
   });
+  var onUploadingListRef = useLatestRef(onUploadingList);
 
   // Sync to the ref on update
   useEffect(function () {
@@ -35,12 +37,16 @@ export function useUploadOperations(_ref) {
   useEffect(function () {
     operationsRef.current.uploadingList = uploadingList;
   }, [uploadingList]);
+
+  // 回调 prop 不进依赖数组：消费方传内联箭头时每次渲染都是新引用，effect 会跟着
+  // 重跑并再调一次回调 —— 回调里 setState 就是死循环（详见 Input/TextArea 的说明）
   useEffect(function () {
     if (!Equal.ObjEqual(uploadingList, lastUploadList)) {
-      onUploadingList === null || onUploadingList === void 0 || onUploadingList(deepCopy(uploadingList));
+      var _onUploadingListRef$c;
+      (_onUploadingListRef$c = onUploadingListRef.current) === null || _onUploadingListRef$c === void 0 || _onUploadingListRef$c.call(onUploadingListRef, deepCopy(uploadingList));
       setLastUploadList(deepCopy(uploadingList));
     }
-  }, [uploadingList, lastUploadList, onUploadingList]);
+  }, [uploadingList, lastUploadList, onUploadingListRef]);
 
   // Cleanup function
   useEffect(function () {

package/es/hooks/useLatestRef.d.ts

@@ -0,0 +1,24 @@
+/// <reference types="react" />
+/**
+ * 把一个每次渲染都可能换引用的值（通常是回调 prop）装进一个**引用恒定**的 ref。
+ *
+ * 用途只有一个：让 effect 不必把回调放进依赖数组。
+ * 回调放进依赖数组、effect 体内又调它，是一条会让消费方死循环的写法——
+ * 消费方传内联箭头（`onChange={(v) => setX(v)}`，React 里最常见的写法）时
+ * 每次渲染都是新引用 → effect 重跑 → 调回调 → 父级 setState → 再渲染 →
+ * 又是新引用 …… 直到 React 抛 `Maximum update depth exceeded`。
+ *
+ * ```ts
+ * const onDoneRef = useLatestRef(onDone);
+ * useEffect(() => {
+ *   const t = setTimeout(() => onDoneRef.current?.(), 1000);
+ *   return () => clearTimeout(t);
+ * }, [onDoneRef]); // 只在挂载时跑一次，且永远调到最新的 onDone
+ * ```
+ *
+ * 注意：渲染期间就地赋值。React 官方对 ref 的约束是「不要在渲染中**读**可变值」，
+ * 写入最新的 props 是 useEffectEvent 落地前的通行做法（ahooks 的 `useLatest`、
+ * React 文档里的 `useEvent` polyfill 都是这么写的）。
+ */
+export declare function useLatestRef<T>(value: T): import("react").MutableRefObject<T>;
+export default useLatestRef;

package/es/hooks/useLatestRef.js

@@ -0,0 +1,29 @@
+import { useRef } from "react";
+
+/**
+ * 把一个每次渲染都可能换引用的值（通常是回调 prop）装进一个**引用恒定**的 ref。
+ *
+ * 用途只有一个：让 effect 不必把回调放进依赖数组。
+ * 回调放进依赖数组、effect 体内又调它，是一条会让消费方死循环的写法——
+ * 消费方传内联箭头（`onChange={(v) => setX(v)}`，React 里最常见的写法）时
+ * 每次渲染都是新引用 → effect 重跑 → 调回调 → 父级 setState → 再渲染 →
+ * 又是新引用 …… 直到 React 抛 `Maximum update depth exceeded`。
+ *
+ * ```ts
+ * const onDoneRef = useLatestRef(onDone);
+ * useEffect(() => {
+ *   const t = setTimeout(() => onDoneRef.current?.(), 1000);
+ *   return () => clearTimeout(t);
+ * }, [onDoneRef]); // 只在挂载时跑一次，且永远调到最新的 onDone
+ * ```
+ *
+ * 注意：渲染期间就地赋值。React 官方对 ref 的约束是「不要在渲染中**读**可变值」，
+ * 写入最新的 props 是 useEffectEvent 落地前的通行做法（ahooks 的 `useLatest`、
+ * React 文档里的 `useEvent` polyfill 都是这么写的）。
+ */
+export function useLatestRef(value) {
+  var ref = useRef(value);
+  ref.current = value;
+  return ref;
+}
+export default useLatestRef;

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

@@ -8,6 +8,7 @@ var _react = _interopRequireWildcard(require("react"));
 var _indexModule = _interopRequireDefault(require("../index.module.scss"));
 var echarts = _interopRequireWildcard(require("echarts"));
 var _bubble = require("../_utils/bubble");
+var _useLatestRef = 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); }
@@ -254,7 +255,10 @@ const Bubble = props => {
       chartInstanceRef.current.setOption(chartOption, true);
     }
   }, [chartOption, data]);
+  const onChartRef = (0, _useLatestRef.useLatestRef)(onChart);
 
+  // 回调 prop 不进依赖数组：消费方传内联箭头时每次渲染都是新引用，effect 会跟着
+  // 重跑并再调一次回调 —— 回调里 setState 就是死循环（详见 Input/TextArea 的说明）
   // Initialize the chart
   (0, _react.useEffect)(() => {
     if (!chartRef.current) return;
@@ -267,7 +271,7 @@ const Bubble = props => {
       chart = echarts.init(chartRef.current);
       chartInstanceRef.current = chart;
       // Call the onChart callback on first initialization
-      onChart?.(chart);
+      onChartRef.current?.(chart);
     }
 
     // Resize first so echarts picks up the correct container size, then apply the option
@@ -289,7 +293,7 @@ const Bubble = props => {
         chartInstanceRef.current?.off("click", onClick);
       }
     };
-  }, [chartOption, containerSize.width, containerSize.height, handleResize, onChart, onClick]);
+  }, [chartOption, containerSize.width, containerSize.height, handleResize, onChartRef, onClick]);
 
   // Dispose the chart instance when the component unmounts
   (0, _react.useEffect)(() => {

package/lib/components/Chart/Common/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 = 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); }
@@ -41,7 +42,10 @@ const Common = props => {
     if (!el || el.clientWidth === 0 || el.clientHeight === 0) return;
     chartInstanceRef.current?.resize();
   }, []);
+  const onChartRef = (0, _useLatestRef.useLatestRef)(onChart);
 
+  // 回调 prop 不进依赖数组：消费方传内联箭头时每次渲染都是新引用，effect 会跟着
+  // 重跑并再调一次回调 —— 回调里 setState 就是死循环（详见 Input/TextArea 的说明）
   // Initialize the chart
   (0, _react.useEffect)(() => {
     if (!chartRef.current || !containerReady) return;
@@ -57,7 +61,7 @@ const Common = props => {
     chart.setOption(chartOption, true);
 
     // Chart-ready callback (can be used for legend auto-scroll, etc.)
-    onChart?.(chart);
+    onChartRef.current?.(chart);
 
     // Add resize listener
     window.addEventListener("resize", handleResize);
@@ -72,7 +76,7 @@ const Common = props => {
     return () => {
       window.removeEventListener("resize", handleResize);
     };
-  }, [chartOption, handleResize, onChart, containerReady]);
+  }, [chartOption, handleResize, onChartRef, containerReady]);
 
   // Clean up resources on component unmount
   (0, _react.useEffect)(() => {

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

@@ -11,6 +11,7 @@ var echarts = _interopRequireWildcard(require("echarts"));
 var _heatmap = require("../_utils/heatmap");
 var _chartTheme = require("../_utils/chartTheme");
 var _useIsDark = _interopRequireDefault(require("../../../hooks/useIsDark"));
+var _useLatestRef = 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); }
@@ -191,7 +192,10 @@ const Heatmap = props => {
     if (!el || el.clientWidth === 0 || el.clientHeight === 0) return;
     chartInstanceRef.current?.resize();
   }, []);
+  const onChartRef = (0, _useLatestRef.useLatestRef)(onChart);
 
+  // 回调 prop 不进依赖数组：消费方传内联箭头时每次渲染都是新引用，effect 会跟着
+  // 重跑并再调一次回调 —— 回调里 setState 就是死循环（详见 Input/TextArea 的说明）
   // Initialize the chart
   (0, _react.useEffect)(() => {
     if (!chartRef.current || !containerReady) return;
@@ -202,7 +206,7 @@ const Heatmap = props => {
       chart = echarts.init(chartRef.current);
       chartInstanceRef.current = chart;
       // Call the onChart callback on first initialization
-      onChart?.(chart);
+      onChartRef.current?.(chart);
     }
 
     // Apply the option
@@ -229,7 +233,7 @@ const Heatmap = props => {
         chartInstanceRef.current?.off("click", onClick);
       }
     };
-  }, [chartOption, handleResize, onChart, onClick, containerReady]);
+  }, [chartOption, handleResize, onChartRef, onClick, containerReady]);
 
   // Clean up resources when the component unmounts
   (0, _react.useEffect)(() => {

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

@@ -11,6 +11,7 @@ var _react = _interopRequireWildcard(require("react"));
 var _hooks = require("./_hooks");
 var _option = require("./_utils/option");
 var _indexModule = _interopRequireDefault(require("../../index.module.scss"));
+var _useLatestRef = 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); }
@@ -84,13 +85,17 @@ const ChartPie3D = props => {
     yOffset,
     autoRotate
   });
+  const onChartRef = (0, _useLatestRef.useLatestRef)(onChart);
+
+  // 回调 prop 不进依赖数组：消费方传内联箭头时每次渲染都是新引用，effect 会跟着
+  // 重跑并再调一次回调 —— 回调里 setState 就是死循环（详见 Input/TextArea 的说明）
   (0, _react.useEffect)(() => {
     if (!chartRef.current || !containerReady) return;
     let chart = chartInstanceRef.current;
     if (!chart) {
       chart = echarts.init(chartRef.current);
       chartInstanceRef.current = chart;
-      onChart?.(chart);
+      onChartRef.current?.(chart);
     }
     chart.setOption(chartOption, true);
     optionRef.current = chartOption;
@@ -114,7 +119,7 @@ const ChartPie3D = props => {
         }
       }
     };
-  }, [chartOption, handleResize, handleMouseOver, handleGlobalOut, onChart, onClick, containerReady]);
+  }, [chartOption, handleResize, handleMouseOver, handleGlobalOut, onChartRef, onClick, containerReady]);
   (0, _react.useEffect)(() => {
     return () => {
       if (resizeObserverRef.current) {