@hsu-react/ui 2.5.2 → 2.5.4

package/src/components/Input/TextArea/index.tsx

@@ -6,6 +6,7 @@ import React, { ReactNode, useEffect, useRef, useState } from "react";
 
 import classNames from "classnames";
 import styles from "./index.module.scss";
+import { useLatestRef } from "../../../hooks/useLatestRef";
 
 export interface TextAreaProps
   extends Omit<
@@ -43,51 +44,71 @@ const TextArea: React.FC<TextAreaProps> = (props) => {
     style,
     ...inputConfig
   } = props;
-  const [isComposing, setComposing] = useState<boolean>(false);
   const ref = useRef<TextAreaRef>(null);
   const [focused, setFocused] = useState<boolean>(false);
 
   // On initialization, prefer value, then fall back to defaultValue
   const initialValue =
     value !== undefined
-      ? value?.toString() ?? ""
+      ? (value?.toString() ?? "")
       : defaultValue !== undefined
-      ? defaultValue?.toString() ?? ""
-      : "";
+        ? (defaultValue?.toString() ?? "")
+        : "";
 
   const [_value, setValue] = useState<string>(initialValue);
-  const [lastValue, setLastValue] = useState<string>(initialValue);
   const [hasError, setHasError] = useState<boolean>(false);
   const prevValueRef = useRef<typeof value>(undefined);
 
-  useEffect(() => {
-    if (!isComposing && _value !== lastValue) {
-      const trimmedValue = _value.trim();
-      const finalValue = trimmedValue === "" ? "" : _value;
-      setLastValue(finalValue);
-      onChange?.(finalValue);
-    }
-  }, [isComposing, onChange, _value, lastValue]);
+  const getRefRef = useLatestRef(getRef);
+
+  // 输入法组字期间不往外通知。放 ref 不放 state：它只影响「要不要发通知」，
+  // 不参与渲染，而且必须在同一次事件里立刻生效
+  const composingRef = useRef(false);
+  // 最近一次通知出去的原文。只用来去掉 compositionend 与 input 两个事件的重复通知
+  const notifiedRef = useRef<string>(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` 的引用稳不稳定完全不影响正确性：永远调到最新的那个回调，
+   * 且只在真的有新文本时调一次。
+   */
+  const notify = (next: string) => {
+    if (next === notifiedRef.current) return;
+    notifiedRef.current = next;
+    // 全是空白等同于空：外部拿到的是 ""，但输入框里用户敲的空格照旧留着
+    onChange?.(next.trim() === "" ? "" : next);
+  };
 
   useEffect(() => {
     // Update internal state only when the external value prop actually changes
     if (prevValueRef.current !== value) {
       prevValueRef.current = value;
 
-      if (value !== undefined) {
-        setValue(value?.toString());
-        setLastValue(value?.toString());
-      } else {
-        // Clear only on initialization or when explicitly set to undefined externally
-        setValue("");
-        setLastValue("");
-      }
+      // 外部把值改了，之前通知过什么就不作数了，重新以外部值为准
+      const next = value !== undefined ? (value?.toString() ?? "") : "";
+      notifiedRef.current = next;
+      setValue(next);
     }
   }, [value]);
 
+  // 只在挂载时把 ref 交出去。`getRef` 进依赖数组同样会被内联箭头带着每次渲染重跑，
+  // 消费方在里面 setState 就是一个死循环
   useEffect(() => {
-    getRef?.(ref.current);
-  }, [getRef]);
+    getRefRef.current?.(ref.current);
+  }, [getRefRef]);
 
   useEffect(() => {
     // Use a MutationObserver to watch for error state changes
@@ -95,7 +116,7 @@ const TextArea: React.FC<TextAreaProps> = (props) => {
       if (ref.current?.resizableTextArea?.textArea) {
         const textAreaElement = ref.current.resizableTextArea.textArea;
         const hasErrorClass = textAreaElement.classList.contains(
-          "ant-input-status-error"
+          "ant-input-status-error",
         );
         setHasError(hasErrorClass);
       }
@@ -135,16 +156,21 @@ const TextArea: React.FC<TextAreaProps> = (props) => {
       {prefix}
       <AntdTextArea
         ref={ref}
-        onCompositionStart={() => setComposing(true)}
-        onCompositionEnd={() => {
-          setTimeout(() => {
-            setComposing(false);
-          }, 1);
+        onCompositionStart={() => {
+          composingRef.current = true;
+        }}
+        onCompositionEnd={(e) => {
+          composingRef.current = false;
+          // 组完字的那一下自己发通知。浏览器之间 compositionend 与 input 的先后
+          // 不一致，`notify` 里按原文去重，两种顺序都只会发出一次
+          notify(e.currentTarget.value);
         }}
         value={_value}
         autoSize={disabled && text ? autoSize || { minRows: 1 } : autoSize}
         onChange={(e) => {
-          setValue(e.target.value);
+          const next = e.target.value;
+          setValue(next);
+          if (!composingRef.current) notify(next);
         }}
         onFocus={(e) => {
           setFocused(true);

package/src/components/Input/index.test.tsx

@@ -0,0 +1,189 @@
+import React, { useState } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { makeAutoObservable } from "mobx";
+import { observer } from "mobx-react-lite";
+
+import Input from ".";
+import Slider from "../Slider";
+
+/**
+ * `Input` / `Password` / `Search` / `Number` / `Slider` 与 `TextArea` 是同一套写法，
+ * 也曾是同一个缺陷：`onChange` 进 effect 依赖数组、effect 体内又调它。
+ * 这里逐个盯住「消费方传内联箭头也不会死循环」这条底线。
+ */
+
+class Store {
+  private _v = "";
+  constructor() {
+    makeAutoObservable(this);
+  }
+  get v() {
+    return this._v;
+  }
+  set = (v: string) => {
+    this._v = v;
+  };
+}
+
+const type = (el: HTMLElement, value: string) =>
+  fireEvent.change(el, { target: { value } });
+
+const cases: Array<[string, React.FC<{ value: string; onChange: (v: string) => void }>]> = [
+  ["Input", (p) => <Input {...p} />],
+  ["Input.Password", (p) => <Input.Password {...p} />],
+  ["Input.Search", (p) => <Input.Search {...p} />],
+];
+
+describe.each(cases)("%s", (name, Cmp) => {
+  it("父级是 MobX observer、又传内联箭头时不进入无限循环", async () => {
+    const store = new Store();
+    const spy = vi.fn();
+    const Page = observer(() => (
+      <Cmp
+        value={store.v}
+        onChange={(v) => {
+          spy(v);
+          store.set(v);
+        }}
+      />
+    ));
+
+    render(<Page />);
+    const el = document.querySelector("input") as HTMLInputElement;
+    type(el, "a");
+
+    await waitFor(() => expect(spy).toHaveBeenCalledWith("a"));
+    await new Promise((r) => setTimeout(r, 100));
+    expect(spy.mock.calls.length).toBeLessThanOrEqual(2);
+    expect(store.v).toBe("a");
+  });
+
+  it("受控回写、外部改值、组字期间不通知", async () => {
+    const spy = vi.fn();
+    const Page = () => {
+      const [v, setV] = useState("");
+
+      return (
+        <Cmp
+          value={v}
+          onChange={(next) => {
+            spy(next);
+            setV(next);
+          }}
+        />
+      );
+    };
+
+    render(<Page />);
+    const el = document.querySelector("input") as HTMLInputElement;
+
+    fireEvent.compositionStart(el);
+    type(el, "n");
+    await new Promise((r) => setTimeout(r, 20));
+    expect(spy).not.toHaveBeenCalled();
+
+    fireEvent.compositionEnd(el, { currentTarget: el });
+    type(el, "你");
+    await waitFor(() => expect(spy).toHaveBeenCalledWith("你"));
+    expect(el.value).toBe("你");
+  });
+});
+
+describe("Input", () => {
+  it("escapeCharacters：对内显示原文，对外给转义值", async () => {
+    const spy = vi.fn();
+    render(<Input escapeCharacters={[","]} onChange={spy} />);
+    const el = screen.getByRole("textbox") as HTMLInputElement;
+
+    type(el, "a,b");
+    await waitFor(() => expect(spy).toHaveBeenCalledWith("a\\,b"));
+    expect(el.value).toBe("a,b");
+    expect(spy.mock.calls.length).toBe(1);
+  });
+
+  it("外部改 value 会同步进输入框，且不额外触发 onChange", async () => {
+    const spy = vi.fn();
+    const { rerender } = render(<Input value="a" onChange={spy} />);
+    const el = screen.getByRole("textbox") as HTMLInputElement;
+    expect(el.value).toBe("a");
+
+    rerender(<Input value="b" onChange={spy} />);
+    await waitFor(() => expect(el.value).toBe("b"));
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it("内联 getRef 只在挂载时交一次 ref", async () => {
+    const seen: unknown[] = [];
+    const Page = () => {
+      const [, setTick] = useState(0);
+
+      return (
+        <Input
+          getRef={(r) => {
+            seen.push(r);
+            setTick((n) => n + 1);
+          }}
+        />
+      );
+    };
+
+    render(<Page />);
+    await new Promise((r) => setTimeout(r, 100));
+    expect(seen.length).toBe(1);
+  });
+});
+
+describe("Input.Number", () => {
+  it("父级把值转成数字回写、又传内联箭头时不进入无限循环", async () => {
+    const spy = vi.fn();
+    const Page = () => {
+      const [v, setV] = useState<string | number>("");
+
+      return (
+        <Input.Number
+          value={v}
+          onChange={(next) => {
+            spy(next);
+            // 模拟上游把值转成数字（FormItem 的默认行为），制造一个回环
+            setV(next === "" ? "" : Number(next));
+          }}
+        />
+      );
+    };
+
+    render(<Page />);
+    const el = document.querySelector("input") as HTMLInputElement;
+
+    type(el, "1");
+    await waitFor(() => expect(spy).toHaveBeenCalledWith("1"));
+    await new Promise((r) => setTimeout(r, 100));
+    expect(spy.mock.calls.length).toBeLessThanOrEqual(2);
+    expect(el.value).toBe("1");
+  });
+});
+
+describe("Slider", () => {
+  it("内联箭头不循环", async () => {
+    const spy = vi.fn();
+    const Page = () => {
+      const [v, setV] = useState(0);
+
+      return (
+        <Slider
+          value={v}
+          onChange={(next) => {
+            spy(next);
+            setV(next as number);
+          }}
+        />
+      );
+    };
+
+    const { container } = render(<Page />);
+    expect(container.querySelector(".ant-slider")).toBeTruthy();
+    await new Promise((r) => setTimeout(r, 50));
+    // 没有交互就不该有任何通知
+    expect(spy).not.toHaveBeenCalled();
+  });
+});

package/src/components/Input/index.tsx

@@ -14,7 +14,7 @@ import TextArea, { TextAreaProps } from "./TextArea";
 import classNames from "classnames";
 import styles from "./index.module.scss";
 import RangeInput, { RangeInputProps } from "./Range";
-import { useDebounceEffect } from "ahooks";
+import { useLatestRef } from "../../hooks/useLatestRef";
 
 export interface InputProps extends Omit<
   AntdInputProps,
@@ -54,8 +54,11 @@ const Input: InputFC = (props) => {
     escapeCharacters,
     ...inputConfig
   } = props;
-  const [isComposing, setComposing] = useState<boolean>(false);
   const ref = useRef<InputRef>(null);
+  const getRefRef = useLatestRef(getRef);
+  // 输入法组字期间不往外通知。放 ref 不放 state：它只决定「要不要发通知」，
+  // 不参与渲染，而且必须在同一次事件里立刻生效
+  const composingRef = useRef(false);
 
   // Handle escaping: if the value contains characters listed in escapeCharacters, prefix them with an escape
   const escapeValue = useCallback(
@@ -143,25 +146,23 @@ const Input: InputFC = (props) => {
   const initialValue = getInitialValue();
 
   const [_value, setValue] = useState<string>(initialValue);
-  const [lastValue, setLastValue] = useState<string>(initialValue);
   const prevValueRef = useRef<typeof value>(undefined);
-
-  useDebounceEffect(
-    () => {
-      if (!isComposing && _value !== lastValue) {
-        const trimmedValue = _value.trim();
-        const finalValue = trimmedValue === "" ? "" : _value;
-        setLastValue(finalValue);
-        // If escapeCharacters is set and the value matches, return the escaped value
-        const escapedValue = escapeValue(finalValue);
-        onChange?.(escapedValue);
-      }
-    },
-    [_value, isComposing, lastValue, onChange, escapeValue],
-    {
-      wait: 10,
-    },
-  );
+  // 最近一次通知出去的原文（未转义）。只用来去掉 compositionend 与 input
+  // 两个事件的重复通知
+  const notifiedRef = useRef<string>(initialValue);
+
+  /**
+   * `onChange` 是「用户改了输入」这个**事件**的通知，不是从 state 推导出来的结果，
+   * 所以在事件处理里发，不在 effect 里发。详见 `TextArea/index.tsx` 里那段说明——
+   * 旧写法（依赖数组里放 `onChange`、体内又调它、用 state 记「通知过没有」）
+   * 会让传内联箭头的消费方死循环。
+   */
+  const notify = (next: string) => {
+    if (next === notifiedRef.current) return;
+    notifiedRef.current = next;
+    // 全是空白等同于空；escapeCharacters 命中时对外给转义后的值
+    onChange?.(escapeValue(next.trim() === "" ? "" : next));
+  };
 
   useEffect(() => {
     // Update internal state only when the external value prop actually changes
@@ -173,19 +174,21 @@ const Input: InputFC = (props) => {
           typeof value === "number" ? `${value}` : value?.toString();
         // Unescape before displaying
         const 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(() => {
-    getRef?.(ref.current);
-  }, [getRef]);
+    getRefRef.current?.(ref.current);
+  }, [getRefRef]);
 
   return (
     <Tooltip placement="topLeft" {...tooltip}>
@@ -193,11 +196,14 @@ const Input: InputFC = (props) => {
         ref={ref}
         disabled={disabled}
         placeholder={disabled ? "" : placeholder}
-        onCompositionStart={() => setComposing(true)}
-        onCompositionEnd={() => {
-          setTimeout(() => {
-            setComposing(false);
-          }, 1);
+        onCompositionStart={() => {
+          composingRef.current = true;
+        }}
+        onCompositionEnd={(e) => {
+          composingRef.current = false;
+          // 组完字的那一下自己发通知。浏览器之间 compositionend 与 input 的先后
+          // 不一致，`notify` 里按原文去重，两种顺序都只会发出一次
+          notify(unescapeValue(e.currentTarget.value));
         }}
         value={_value}
         onChange={(e) => {
@@ -205,6 +211,7 @@ const Input: InputFC = (props) => {
           const inputValue = e.target.value;
           const unescapedInput = unescapeValue(inputValue);
           setValue(unescapedInput);
+          if (!composingRef.current) notify(unescapedInput);
         }}
         className={classNames(styles.antdInput, className)}
         type={type}

package/src/components/Select/_hooks/useSelectInputOptions.ts

@@ -1,5 +1,6 @@
 import { useEffect, useState } from "react";
 import { SelectOption } from "..";
+import { useLatestRef } from "../../../hooks/useLatestRef";
 
 interface UseSelectInputOptionsProps {
   searchValue: string;
@@ -20,19 +21,15 @@ export function useSelectInputOptions({
   optionsLength,
 }: UseSelectInputOptionsProps) {
   const [inputOptions, setInputOptions] = useState<SelectOption[]>([]);
+  const onSearchRef = useLatestRef(onSearch);
 
+  // 回调 prop 不进依赖数组：消费方传内联箭头时每次渲染都是新引用，effect 会跟着
+  // 重跑并再调一次回调 —— 回调里 setState 就是死循环（详见 Input/TextArea 的说明）
   useEffect(() => {
     if (!isComposing) {
-      onSearch?.(searchValue);
+      onSearchRef.current?.(searchValue);
     }
-  }, [
-    inputOptions,
-    isComposing,
-    onChange,
-    onSearch,
-    optionsLength,
-    searchValue,
-  ]);
+  }, [inputOptions, isComposing, onSearchRef, optionsLength, searchValue]);
 
   return { inputOptions, setInputOptions };
 }

package/src/components/Slider/index.tsx

@@ -2,7 +2,7 @@ import {
   Slider as AntdSlider,
   SliderSingleProps as AntdSliderSingleProps,
 } 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";
@@ -14,27 +14,37 @@ export interface SliderProps extends AntdSliderSingleProps {
 const Slider: React.FC<SliderProps> = (props) => {
   const { className, value = 0, topValue, onChange, ...sliderConfig } = props;
   const [_value, setValue] = useState<number>(value);
-  const [lastValue, setLastValue] = useState<number>(value);
+  // 最近一次通知出去的值，代替原来那个用 state 记账的写法
+  const notifiedRef = useRef<number>(value);
 
-  useEffect(() => {
-    if (_value !== lastValue) {
-      setLastValue(_value);
-      onChange?.(_value);
-    }
-  }, [lastValue, onChange, _value]);
+  /**
+   * `onChange` 是「用户拖了滑块」这个**事件**的通知，不是从 state 推导出来的结果，
+   * 所以在事件处理里发，不在 effect 里发。详见 `Input/TextArea/index.tsx` 里那段
+   * 说明——旧写法（依赖数组里放 `onChange`、体内又调它、用 state 记「通知过没有」）
+   * 会让传内联箭头的消费方死循环。
+   */
+  const handleChange = (next: number) => {
+    setValue(next);
+    if (next === notifiedRef.current) return;
+    notifiedRef.current = next;
+    onChange?.(next);
+  };
 
+  // 外部值（`value` / `topValue`）变了才回写，不跟着通知走
   useEffect(() => {
-    if ((topValue || value) !== lastValue) {
-      setValue(topValue || value);
+    const next = topValue || value;
+    if (next !== notifiedRef.current) {
+      notifiedRef.current = next;
+      setValue(next);
     }
-  }, [lastValue, topValue, value]);
+  }, [topValue, value]);
 
   return (
     <AntdSlider
       className={classNames([styles.slider, className])}
       tooltip={{ open: false }}
       value={_value}
-      onChange={setValue}
+      onChange={handleChange}
       {...sliderConfig}
     />
   );

package/src/components/Upload/_hooks/useUploadFileList.ts

@@ -2,6 +2,7 @@ import { useEffect, useState } from "react";
 import { UploadFile } from "antd";
 import { deepCopy, Equal } from "hsu-utils";
 import { extractFileUrl } from "../_utils";
+import { useLatestRef } from "../../../hooks/useLatestRef";
 
 interface UseUploadFileListProps {
   fileList?: UploadFile[];
@@ -19,7 +20,10 @@ export function useUploadFileList({
 }: UseUploadFileListProps) {
   const [_fileList, setFilelist] = useState<UploadFile[]>([]);
   const [lastFileList, setLastFileList] = useState<UploadFile[]>([]);
+  const onChangeRef = useLatestRef(onChange);
 
+  // 回调 prop 不进依赖数组：消费方传内联箭头时每次渲染都是新引用，effect 会跟着
+  // 重跑并再调一次回调 —— 回调里 setState 就是死循环（详见 Input/TextArea 的说明）
   useEffect(() => {
     if (rmFile) {
       const file = _fileList.find((item) => item.uid === rmFile);
@@ -27,14 +31,14 @@ export function useUploadFileList({
       if (file) {
         setFilelist(filteredList);
         setTimeout(() => {
-          onChange?.({
+          onChangeRef.current?.({
             file,
             fileList: filteredList,
           });
         }, 100);
       }
     }
-  }, [_fileList, onChange, rmFile]);
+  }, [_fileList, onChangeRef, rmFile]);
 
   useEffect(() => {
     if (!Equal.ObjEqual(fileList ?? [], lastFileList)) {

package/src/components/Upload/_hooks/useUploadOperations.ts

@@ -1,6 +1,7 @@
 import { useEffect, useRef, useState } from "react";
 import { deepCopy, Equal } from "hsu-utils";
 import { UploadingList } from "..";
+import { useLatestRef } from "../../../hooks/useLatestRef";
 
 interface UseUploadOperationsProps {
   onUploadingList?: (list: UploadingList) => void;
@@ -25,6 +26,8 @@ export function useUploadOperations({
     uploadingList: {},
   });
 
+  const onUploadingListRef = useLatestRef(onUploadingList);
+
   // Sync to the ref on update
   useEffect(() => {
     operationsRef.current.downloading = downloading;
@@ -34,12 +37,14 @@ export function useUploadOperations({
     operationsRef.current.uploadingList = uploadingList;
   }, [uploadingList]);
 
+  // 回调 prop 不进依赖数组：消费方传内联箭头时每次渲染都是新引用，effect 会跟着
+  // 重跑并再调一次回调 —— 回调里 setState 就是死循环（详见 Input/TextArea 的说明）
   useEffect(() => {
     if (!Equal.ObjEqual(uploadingList, lastUploadList)) {
-      onUploadingList?.(deepCopy(uploadingList));
+      onUploadingListRef.current?.(deepCopy(uploadingList));
       setLastUploadList(deepCopy(uploadingList));
     }
-  }, [uploadingList, lastUploadList, onUploadingList]);
+  }, [uploadingList, lastUploadList, onUploadingListRef]);
 
   // Cleanup function
   useEffect(() => {

package/src/hooks/useLatestRef.ts

@@ -0,0 +1,31 @@
+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<T>(value: T) {
+  const ref = useRef(value);
+  ref.current = value;
+
+  return ref;
+}
+
+export default useLatestRef;

package/src/layout/Menu/index.md

@@ -28,6 +28,17 @@ import Layout from "@hsu-react/ui/es/layout";
 
 `meta.secondary` 标记的路由进入**二级菜单**：主菜单只显示到一级，点进去之后左侧换成该模块的次级菜单，顶部可用 `secondaryHeader` 放返回入口、标题或检索框。
 
+### 滚动与滚动条
+
+`inline` 模式下本组件**自带滚动容器**：外层包一个撑满高度、自己不滚的宿主，菜单根 `overflow-y: auto` 负责滚。
+所以把 `Menu` 塞进任何一个**有确定高度**的容器（antd 的 `Layout.Sider`、或自己的 div）即可，不需要再补 `overflow` 规则；
+展开 / 收起子菜单的动画期间也不会有滚动条闪出来。宿主没有确定高度时菜单会被撑开、退回由页面滚，这时请给宿主一个高度。
+
+滚动条的**外观（显 / 隐 / 配色）本组件不管**，交给消费方的全局样式（`::-webkit-scrollbar` 那一套）。
+组件里刻意不写 `scrollbar-width` / `scrollbar-color`：**Chrome 121+ 一旦读到它们的非默认值，就会整套忽略该元素上的
+`::-webkit-scrollbar` 规则**，库里无差别写一句就会悄悄废掉消费方全站的滚动条皮肤。库内其它地方若确实需要这两个属性，
+必须锁在 `@supports (-moz-appearance: none)` 里，只给 Firefox 看。
+
 ## API
 
 | 属性 | 说明 | 类型 | 默认值 |