@hsu-react/ui 2.5.2 → 2.5.3

package/es/layout/Menu/index.js

@@ -184,12 +184,30 @@ var Menu = function Menu(props) {
   }));
 
   // 次级菜单默认带一段头部（至少给出返回入口），调用方可用 secondaryHeader 整块换掉
-  return secondary ? /*#__PURE__*/_jsxs("div", {
-    className: styles.secondaryWrap,
-    children: [secondaryHeader !== null && secondaryHeader !== void 0 ? secondaryHeader : /*#__PURE__*/_jsx(SecondaryHeader, {
-      collapsed: collapsed,
-      theme: theme
-    }), menu]
+  if (secondary) {
+    return /*#__PURE__*/_jsxs("div", {
+      className: classNames(styles.scrollHost, styles.secondaryWrap),
+      children: [secondaryHeader !== null && secondaryHeader !== void 0 ? secondaryHeader : /*#__PURE__*/_jsx(SecondaryHeader, {
+        collapsed: collapsed,
+        theme: theme
+      }), menu]
+    });
+  }
+
+  /**
+   * 侧栏（inline）菜单自带滚动宿主：宿主不滚、菜单根滚。
+   *
+   * 不这么做的话「谁滚」就落在消费方的 Sider 上 —— 而 antd 的
+   * `.ant-layout-sider` / `.ant-layout-sider-children` 都没有 overflow，
+   * 展开子菜单的动画期间高度先超出再收回，滚动条会闪一下。几何契约必须由组件
+   * 自己闭合，不能指望每个消费方都补一遍 overflow 规则。
+   *
+   * 横向菜单不需要（rc-overflow 自己收成 “…”），也不能加：那层 div 会把
+   * `.menu` 从 Header 的 flex 行里挪走。
+   */
+  return mode === "inline" ? /*#__PURE__*/_jsx("div", {
+    className: styles.scrollHost,
+    children: menu
   }) : menu;
 };
 export default Menu;

package/es/layout/Menu/index.module.scss

@@ -1,13 +1,6 @@
 // 注意：CSS Module 里的类名都会被哈希，antd 的类名必须写在 :global() 中，否则
 // `.ant-menu-horizontal` 会变成 `.ant-menu-horizontal___xxxxx`，静悄悄地永不生效。
 .menu {
-  &::-webkit-scrollbar {
-    width: 0px;
-    height: 0px;
-  }
-
-  scrollbar-width: none;
-
   // 顶部横向菜单：占满剩余宽度，背景交给外层的导航渐变
   &:global(.ant-menu-horizontal) {
     flex: 1;
@@ -15,6 +8,50 @@
 
     background-color: transparent;
   }
+
+  /* ===== inline（侧栏）：菜单根**就是**那个滚动容器 =====
+     antd 的 `.ant-layout-sider` / `.ant-layout-sider-children` 都没有设 overflow，
+     所以在这条路径上，「谁滚」原本是没人规定的 —— 展开子菜单那 200ms 里
+     rc-motion 会逐帧改高度，容器先超出再收回，滚动条由**当时**恰好溢出的那个
+     元素临时长出来，于是闪一下。
+
+     这里把它定死：菜单根 `flex: 1 / min-height: 0 / overflow-y: auto`，配上外面
+     那层不滚的 `.scrollHost`，中间态怎么抖都轮不到别人显示滚动条；菜单长过一屏
+     时也仍然滚得到底部。 */
+  &:global(.ant-menu-inline),
+  &:global(.ant-menu-inline-collapsed) {
+    flex: 1;
+    min-height: 0px;
+
+    // 横向一律不滚：菜单文字过长时该省略，不该把侧栏推出一条横向滚动条
+    overflow-x: hidden;
+    overflow-y: auto;
+  }
+
+  /* 子菜单在展开 / 收起动画期间被 rc-motion 逐帧改高度。antd 的
+     `.ant-motion-collapse` 自带 overflow hidden，这里补的是**动画结束、类名摘掉
+     之后**那一帧：此时 ul 的高度刚回到 auto，若父级恰好差几像素，浏览器会先画出
+     滚动条再重排。子菜单本来也永远不需要自己滚。 */
+  :global(.ant-menu-sub.ant-menu-inline) {
+    overflow: hidden;
+  }
+
+  /* ===== 滚动条外观：本组件不管，交给消费方 =====
+     这里曾经写着 `scrollbar-width: none` ＋ `::-webkit-scrollbar { width: 0 }`，
+     用「把滚动条永久藏掉」来遮上面那个闪动。现在闪动由 overflow 归属治本了，
+     这份「藏」不但多余，还有两处害处，所以整段删掉：
+
+     1. **Chrome 121+ 一旦读到 `scrollbar-width` / `scrollbar-color` 的非默认值，
+        就会整套忽略该元素上的 `::-webkit-scrollbar` 规则。** 库里无差别写下一句
+        `scrollbar-width: none`，等于在每个消费方的侧栏上悄悄废掉他们全站那套
+        滚动条皮肤，只剩系统细条 —— 而且不报错、很难查。
+        （所以本库任何地方要写这两个属性，都必须锁在
+        `@supports (-moz-appearance: none)` 里，让 Chrome 读不到。）
+     2. 滚动条的「显 / 隐 / 配色」是应用级的设计语言（有的应用要常驻，有的要
+        悬浮才显现），不是菜单组件的行为。库只该规定**谁滚**，不该用高权重规则
+        把可见性堵死、逼消费方回过头来盖。
+
+     消费方在全局写 `::-webkit-scrollbar` 那一套即可，会自然落到菜单根上。 */
 }
 
 // 弹出的子菜单挂在 body 上，够不到 .menu，所以由组件把这个类挂到 popup 上
@@ -37,14 +74,20 @@
   }
 }
 
-// 次级菜单：头部固定在上，菜单撑满剩余高度
-.secondaryWrap {
+/* inline 菜单的滚动宿主：撑满侧栏高度、自己**不滚**，把高度整份让给菜单根。
+   有它在，菜单组件才是自带滚动容器语义的一整块 —— 消费方把 Menu 塞进任何一个
+   有高度的容器（antd 的 Sider、或自己的 div）都不必再补 overflow 规则。 */
+.scrollHost {
   height: 100%;
   display: flex;
   flex-direction: column;
 
+  overflow: hidden;
+}
+
+// 次级菜单：头部固定在上，菜单撑满剩余高度（滚动归属见 .scrollHost）
+.secondaryWrap {
   :global(.ant-menu) {
-    flex: 1;
     border-inline-end: none !important;
   }
 }

package/lib/layout/Menu/index.js

@@ -147,12 +147,30 @@ const Menu = props => {
   });
 
   // 次级菜单默认带一段头部（至少给出返回入口），调用方可用 secondaryHeader 整块换掉
-  return secondary ? /*#__PURE__*/(0, _jsxRuntime.jsxs)("div", {
-    className: _indexModule.default.secondaryWrap,
-    children: [secondaryHeader ?? /*#__PURE__*/(0, _jsxRuntime.jsx)(_SecondaryHeader.default, {
-      collapsed: collapsed,
-      theme: theme
-    }), menu]
+  if (secondary) {
+    return /*#__PURE__*/(0, _jsxRuntime.jsxs)("div", {
+      className: (0, _classnames.default)(_indexModule.default.scrollHost, _indexModule.default.secondaryWrap),
+      children: [secondaryHeader ?? /*#__PURE__*/(0, _jsxRuntime.jsx)(_SecondaryHeader.default, {
+        collapsed: collapsed,
+        theme: theme
+      }), menu]
+    });
+  }
+
+  /**
+   * 侧栏（inline）菜单自带滚动宿主：宿主不滚、菜单根滚。
+   *
+   * 不这么做的话「谁滚」就落在消费方的 Sider 上 —— 而 antd 的
+   * `.ant-layout-sider` / `.ant-layout-sider-children` 都没有 overflow，
+   * 展开子菜单的动画期间高度先超出再收回，滚动条会闪一下。几何契约必须由组件
+   * 自己闭合，不能指望每个消费方都补一遍 overflow 规则。
+   *
+   * 横向菜单不需要（rc-overflow 自己收成 “…”），也不能加：那层 div 会把
+   * `.menu` 从 Header 的 flex 行里挪走。
+   */
+  return mode === "inline" ? /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
+    className: _indexModule.default.scrollHost,
+    children: menu
   }) : menu;
 };
 var _default = exports.default = Menu;

package/lib/layout/Menu/index.module.scss

@@ -1,13 +1,6 @@
 // 注意：CSS Module 里的类名都会被哈希，antd 的类名必须写在 :global() 中，否则
 // `.ant-menu-horizontal` 会变成 `.ant-menu-horizontal___xxxxx`，静悄悄地永不生效。
 .menu {
-  &::-webkit-scrollbar {
-    width: 0px;
-    height: 0px;
-  }
-
-  scrollbar-width: none;
-
   // 顶部横向菜单：占满剩余宽度，背景交给外层的导航渐变
   &:global(.ant-menu-horizontal) {
     flex: 1;
@@ -15,6 +8,50 @@
 
     background-color: transparent;
   }
+
+  /* ===== inline（侧栏）：菜单根**就是**那个滚动容器 =====
+     antd 的 `.ant-layout-sider` / `.ant-layout-sider-children` 都没有设 overflow，
+     所以在这条路径上，「谁滚」原本是没人规定的 —— 展开子菜单那 200ms 里
+     rc-motion 会逐帧改高度，容器先超出再收回，滚动条由**当时**恰好溢出的那个
+     元素临时长出来，于是闪一下。
+
+     这里把它定死：菜单根 `flex: 1 / min-height: 0 / overflow-y: auto`，配上外面
+     那层不滚的 `.scrollHost`，中间态怎么抖都轮不到别人显示滚动条；菜单长过一屏
+     时也仍然滚得到底部。 */
+  &:global(.ant-menu-inline),
+  &:global(.ant-menu-inline-collapsed) {
+    flex: 1;
+    min-height: 0px;
+
+    // 横向一律不滚：菜单文字过长时该省略，不该把侧栏推出一条横向滚动条
+    overflow-x: hidden;
+    overflow-y: auto;
+  }
+
+  /* 子菜单在展开 / 收起动画期间被 rc-motion 逐帧改高度。antd 的
+     `.ant-motion-collapse` 自带 overflow hidden，这里补的是**动画结束、类名摘掉
+     之后**那一帧：此时 ul 的高度刚回到 auto，若父级恰好差几像素，浏览器会先画出
+     滚动条再重排。子菜单本来也永远不需要自己滚。 */
+  :global(.ant-menu-sub.ant-menu-inline) {
+    overflow: hidden;
+  }
+
+  /* ===== 滚动条外观：本组件不管，交给消费方 =====
+     这里曾经写着 `scrollbar-width: none` ＋ `::-webkit-scrollbar { width: 0 }`，
+     用「把滚动条永久藏掉」来遮上面那个闪动。现在闪动由 overflow 归属治本了，
+     这份「藏」不但多余，还有两处害处，所以整段删掉：
+
+     1. **Chrome 121+ 一旦读到 `scrollbar-width` / `scrollbar-color` 的非默认值，
+        就会整套忽略该元素上的 `::-webkit-scrollbar` 规则。** 库里无差别写下一句
+        `scrollbar-width: none`，等于在每个消费方的侧栏上悄悄废掉他们全站那套
+        滚动条皮肤，只剩系统细条 —— 而且不报错、很难查。
+        （所以本库任何地方要写这两个属性，都必须锁在
+        `@supports (-moz-appearance: none)` 里，让 Chrome 读不到。）
+     2. 滚动条的「显 / 隐 / 配色」是应用级的设计语言（有的应用要常驻，有的要
+        悬浮才显现），不是菜单组件的行为。库只该规定**谁滚**，不该用高权重规则
+        把可见性堵死、逼消费方回过头来盖。
+
+     消费方在全局写 `::-webkit-scrollbar` 那一套即可，会自然落到菜单根上。 */
 }
 
 // 弹出的子菜单挂在 body 上，够不到 .menu，所以由组件把这个类挂到 popup 上
@@ -37,14 +74,20 @@
   }
 }
 
-// 次级菜单：头部固定在上，菜单撑满剩余高度
-.secondaryWrap {
+/* inline 菜单的滚动宿主：撑满侧栏高度、自己**不滚**，把高度整份让给菜单根。
+   有它在，菜单组件才是自带滚动容器语义的一整块 —— 消费方把 Menu 塞进任何一个
+   有高度的容器（antd 的 Sider、或自己的 div）都不必再补 overflow 规则。 */
+.scrollHost {
   height: 100%;
   display: flex;
   flex-direction: column;
 
+  overflow: hidden;
+}
+
+// 次级菜单：头部固定在上，菜单撑满剩余高度（滚动归属见 .scrollHost）
+.secondaryWrap {
   :global(.ant-menu) {
-    flex: 1;
     border-inline-end: none !important;
   }
 }

package/package.json

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

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
 
 | 属性 | 说明 | 类型 | 默认值 |

package/src/layout/Menu/index.module.scss

@@ -1,13 +1,6 @@
 // 注意：CSS Module 里的类名都会被哈希，antd 的类名必须写在 :global() 中，否则
 // `.ant-menu-horizontal` 会变成 `.ant-menu-horizontal___xxxxx`，静悄悄地永不生效。
 .menu {
-  &::-webkit-scrollbar {
-    width: 0px;
-    height: 0px;
-  }
-
-  scrollbar-width: none;
-
   // 顶部横向菜单：占满剩余宽度，背景交给外层的导航渐变
   &:global(.ant-menu-horizontal) {
     flex: 1;
@@ -15,6 +8,50 @@
 
     background-color: transparent;
   }
+
+  /* ===== inline（侧栏）：菜单根**就是**那个滚动容器 =====
+     antd 的 `.ant-layout-sider` / `.ant-layout-sider-children` 都没有设 overflow，
+     所以在这条路径上，「谁滚」原本是没人规定的 —— 展开子菜单那 200ms 里
+     rc-motion 会逐帧改高度，容器先超出再收回，滚动条由**当时**恰好溢出的那个
+     元素临时长出来，于是闪一下。
+
+     这里把它定死：菜单根 `flex: 1 / min-height: 0 / overflow-y: auto`，配上外面
+     那层不滚的 `.scrollHost`，中间态怎么抖都轮不到别人显示滚动条；菜单长过一屏
+     时也仍然滚得到底部。 */
+  &:global(.ant-menu-inline),
+  &:global(.ant-menu-inline-collapsed) {
+    flex: 1;
+    min-height: 0px;
+
+    // 横向一律不滚：菜单文字过长时该省略，不该把侧栏推出一条横向滚动条
+    overflow-x: hidden;
+    overflow-y: auto;
+  }
+
+  /* 子菜单在展开 / 收起动画期间被 rc-motion 逐帧改高度。antd 的
+     `.ant-motion-collapse` 自带 overflow hidden，这里补的是**动画结束、类名摘掉
+     之后**那一帧：此时 ul 的高度刚回到 auto，若父级恰好差几像素，浏览器会先画出
+     滚动条再重排。子菜单本来也永远不需要自己滚。 */
+  :global(.ant-menu-sub.ant-menu-inline) {
+    overflow: hidden;
+  }
+
+  /* ===== 滚动条外观：本组件不管，交给消费方 =====
+     这里曾经写着 `scrollbar-width: none` ＋ `::-webkit-scrollbar { width: 0 }`，
+     用「把滚动条永久藏掉」来遮上面那个闪动。现在闪动由 overflow 归属治本了，
+     这份「藏」不但多余，还有两处害处，所以整段删掉：
+
+     1. **Chrome 121+ 一旦读到 `scrollbar-width` / `scrollbar-color` 的非默认值，
+        就会整套忽略该元素上的 `::-webkit-scrollbar` 规则。** 库里无差别写下一句
+        `scrollbar-width: none`，等于在每个消费方的侧栏上悄悄废掉他们全站那套
+        滚动条皮肤，只剩系统细条 —— 而且不报错、很难查。
+        （所以本库任何地方要写这两个属性，都必须锁在
+        `@supports (-moz-appearance: none)` 里，让 Chrome 读不到。）
+     2. 滚动条的「显 / 隐 / 配色」是应用级的设计语言（有的应用要常驻，有的要
+        悬浮才显现），不是菜单组件的行为。库只该规定**谁滚**，不该用高权重规则
+        把可见性堵死、逼消费方回过头来盖。
+
+     消费方在全局写 `::-webkit-scrollbar` 那一套即可，会自然落到菜单根上。 */
 }
 
 // 弹出的子菜单挂在 body 上，够不到 .menu，所以由组件把这个类挂到 popup 上
@@ -37,14 +74,20 @@
   }
 }
 
-// 次级菜单：头部固定在上，菜单撑满剩余高度
-.secondaryWrap {
+/* inline 菜单的滚动宿主：撑满侧栏高度、自己**不滚**，把高度整份让给菜单根。
+   有它在，菜单组件才是自带滚动容器语义的一整块 —— 消费方把 Menu 塞进任何一个
+   有高度的容器（antd 的 Sider、或自己的 div）都不必再补 overflow 规则。 */
+.scrollHost {
   height: 100%;
   display: flex;
   flex-direction: column;
 
+  overflow: hidden;
+}
+
+// 次级菜单：头部固定在上，菜单撑满剩余高度（滚动归属见 .scrollHost）
+.secondaryWrap {
   :global(.ant-menu) {
-    flex: 1;
     border-inline-end: none !important;
   }
 }

package/src/layout/Menu/index.tsx

@@ -193,13 +193,30 @@ const Menu: React.FC<MenuProps> = (props) => {
   );
 
   // 次级菜单默认带一段头部（至少给出返回入口），调用方可用 secondaryHeader 整块换掉
-  return secondary ? (
-    <div className={styles.secondaryWrap}>
-      {secondaryHeader ?? (
-        <SecondaryHeader collapsed={collapsed} theme={theme as "light" | "dark"} />
-      )}
-      {menu}
-    </div>
+  if (secondary) {
+    return (
+      <div className={classNames(styles.scrollHost, styles.secondaryWrap)}>
+        {secondaryHeader ?? (
+          <SecondaryHeader collapsed={collapsed} theme={theme as "light" | "dark"} />
+        )}
+        {menu}
+      </div>
+    );
+  }
+
+  /**
+   * 侧栏（inline）菜单自带滚动宿主：宿主不滚、菜单根滚。
+   *
+   * 不这么做的话「谁滚」就落在消费方的 Sider 上 —— 而 antd 的
+   * `.ant-layout-sider` / `.ant-layout-sider-children` 都没有 overflow，
+   * 展开子菜单的动画期间高度先超出再收回，滚动条会闪一下。几何契约必须由组件
+   * 自己闭合，不能指望每个消费方都补一遍 overflow 规则。
+   *
+   * 横向菜单不需要（rc-overflow 自己收成 “…”），也不能加：那层 div 会把
+   * `.menu` 从 Header 的 flex 行里挪走。
+   */
+  return mode === "inline" ? (
+    <div className={styles.scrollHost}>{menu}</div>
   ) : (
     menu
   );