feat: add option scrollFrozenColsPassThroughToBody

Author: fangsmile

docs/assets/guide/en/interaction/scroll.md

@@ -124,6 +124,8 @@ After enabling frozen columns, if the frozen area's total frozen width exceeds t
 
 After enabling, trackpad horizontal scrolling works inside the corresponding frozen area (without scrolling the body first). When scrollbars are visible, independent horizontal scrollbars for frozen areas will appear at the bottom, supporting dragging the thumb or clicking the track.
 
+By default (`scrollFrozenColsPassThroughToBody: false`), when you reach the start/end of a frozen area, the body will not scroll. If you want to continue scrolling the body after the frozen area hits its boundary, enable this option.
+
 Example:
 
 ```javascript
@@ -135,7 +137,8 @@ const option = {
 
   rightFrozenColCount: 4,
   maxRightFrozenWidth: 320,
-  scrollRightFrozenCols: true
+  scrollRightFrozenCols: true,
+  scrollFrozenColsPassThroughToBody: false
 };
 ```
 

docs/assets/guide/zh/interaction/scroll.md

@@ -124,6 +124,8 @@ VTable 支持在按住 Shift 键时进行横向滚动，或者直接拖拽横向
 
 开启后，触摸板的横向滚动会在对应冻结区域内生效（无需先滚动 body），并且在滚动条可见时底部会出现对应冻结区域的独立横向滚动条，支持拖拽滑块或点击轨道进行滚动。
 
+默认情况下（`scrollFrozenColsPassThroughToBody: false`），在冻结区域滚动到头/尾时不会联动滚动 body；如希望在冻结区域到边界后继续滚动 body，可开启该配置。
+
 示例：
 
 ```javascript
@@ -135,7 +137,8 @@ const option = {
 
   rightFrozenColCount: 4,
   maxRightFrozenWidth: 320,
-  scrollRightFrozenCols: true
+  scrollRightFrozenCols: true,
+  scrollFrozenColsPassThroughToBody: false
 };
 ```
 

docs/assets/option/en/common/option-secondary.md

@@ -116,6 +116,10 @@ Maximum freeze width for right frozen columns (fixed value or percentage). Defau
 
 When the total width of right frozen columns exceeds maxRightFrozenWidth, the right frozen area becomes horizontally scrollable. When enabled, all right frozen columns are kept and you can use trackpad horizontal scrolling or drag the scrollbar inside the frozen area to view the overflow part.
 
+#${prefix} scrollFrozenColsPassThroughToBody(boolean) = false
+
+When horizontally scrolling inside a frozen area (left frozen / right frozen) reaches its boundary, whether to pass the scroll intent through to the body horizontal scrolling. Default is false, which means the body will not scroll when the frozen area is already at its start/end. When enabled, body horizontal scrolling will be triggered if the frozen area can no longer scroll.
+
 #${prefix} unfreezeAllOnExceedsMaxWidth(boolean) = true
 
 Whether to defrost after the maximum freezing width is exceeded. The default value is true. If set to false, it will not unfreeze all columns, but will determine the number of columns to be unfrozen according to the value of maxFrozenWidth.

docs/assets/option/zh/common/option-secondary.md

@@ -120,6 +120,10 @@ containerFit: {
 
 当右侧冻结列总宽度超过 maxRightFrozenWidth 时，右侧冻结区域可横向滚动。开启后会保留全部右侧冻结列，并在冻结区域内通过触摸板横向滚动或拖拽滚动条查看超出部分。
 
+#${prefix} scrollFrozenColsPassThroughToBody(boolean) = false
+
+当在冻结区域（左冻结/右冻结）内横向滚动到边界时，是否将滚动意图“透传”给 body 横向滚动。默认 false，即在冻结区域滚动到头/尾也不会触发 body 滚动；开启后在冻结区域无法继续滚动时会自动联动滚动 body。
+
 #${prefix} unfreezeAllOnExceedsMaxWidth(boolean) = true
 
 超过最大冻结宽度后是否全部解冻，默认 true。如果设置为 false，则不会解冻全部列，而是根据 maxFrozenWidth 的值来决定最终解冻的列数。

packages/vtable/examples/frozen/list-table-scrollable-frozen-cols.ts

@@ -48,6 +48,7 @@ export function createTable() {
     scrollFrozenCols: true,
     maxRightFrozenWidth: 320,
     scrollRightFrozenCols: true,
+    scrollFrozenColsPassThroughToBody: true,
     theme: VTable.themes.DEFAULT.extends({
       scrollStyle: {
         visible: 'scrolling'

packages/vtable/src/event/scroll.ts

@@ -29,6 +29,8 @@ export function handleWhell(event: FederatedWheelEvent, state: StateManager, isW
   const verticalAutoHide = verticalVisible === 'scrolling';
   let usedFrozenHorizontal = false;
   let usedRightFrozenHorizontal = false;
+  let blockedFrozenHorizontal = false;
+  let blockedRightFrozenHorizontal = false;
   if (optimizedDeltaX) {
     // 横向滚动需要判断“滚动意图属于哪个区域”：
     // - body：主滚动域（影响非冻结列）
@@ -70,8 +72,13 @@ export function handleWhell(event: FederatedWheelEvent, state: StateManager, isW
         usedFrozenHorizontal = true;
         state.showHorizontalScrollBar(horizontalAutoHide, 'frozen');
       } else {
-        state.setScrollLeft(state.scroll.horizontalBarPos + optimizedDeltaX, event);
-        state.showHorizontalScrollBar(horizontalAutoHide, 'body');
+        if (state.table.options.scrollFrozenColsPassThroughToBody) {
+          state.setScrollLeft(state.scroll.horizontalBarPos + optimizedDeltaX, event);
+          state.showHorizontalScrollBar(horizontalAutoHide, 'body');
+        } else {
+          blockedFrozenHorizontal = true;
+          state.showHorizontalScrollBar(horizontalAutoHide, 'frozen');
+        }
       }
     } else if (rightFrozenColsScrollable && isInRightFrozenViewport) {
       const maxRightFrozenScrollLeft = state.table.getRightFrozenColsOffset();
@@ -87,8 +94,13 @@ export function handleWhell(event: FederatedWheelEvent, state: StateManager, isW
         usedRightFrozenHorizontal = true;
         state.showHorizontalScrollBar(horizontalAutoHide, 'rightFrozen');
       } else {
-        state.setScrollLeft(state.scroll.horizontalBarPos + optimizedDeltaX, event);
-        state.showHorizontalScrollBar(horizontalAutoHide, 'body');
+        if (state.table.options.scrollFrozenColsPassThroughToBody) {
+          state.setScrollLeft(state.scroll.horizontalBarPos + optimizedDeltaX, event);
+          state.showHorizontalScrollBar(horizontalAutoHide, 'body');
+        } else {
+          blockedRightFrozenHorizontal = true;
+          state.showHorizontalScrollBar(horizontalAutoHide, 'rightFrozen');
+        }
       }
     } else {
       state.setScrollLeft(state.scroll.horizontalBarPos + optimizedDeltaX, event);
@@ -107,7 +119,9 @@ export function handleWhell(event: FederatedWheelEvent, state: StateManager, isW
       (Math.abs(deltaY) >= Math.abs(deltaX) && deltaY !== 0 && isVerticalScrollable(deltaY, state)) ||
       (Math.abs(deltaY) <= Math.abs(deltaX) &&
         deltaX !== 0 &&
-        (usedFrozenHorizontal
+        (blockedFrozenHorizontal || blockedRightFrozenHorizontal
+          ? false
+          : usedFrozenHorizontal
           ? state.table.getFrozenColsOffset() > 0
           : usedRightFrozenHorizontal
           ? state.table.getRightFrozenColsOffset() > 0

packages/vtable/src/ts-types/base-table.ts

@@ -348,6 +348,18 @@ export interface BaseTableConstructorOptions {
    */
   scrollRightFrozenCols?: boolean;
 
+  /**
+   * 冻结区域滚动到边界时，是否自动“透传”给 body 横向滚动。
+   *
+   * - `false`（默认）：在冻结区域内滚动时，即使滚动到头/尾也不会触发 body 横向滚动
+   * - `true`：当冻结区域无法继续滚动时，将剩余滚动意图交由 body 横向滚动处理
+   *
+   * 说明：
+   * - 仅对鼠标滚轮/触摸板触发的横向滚动（wheel）生效
+   * - 仅在 `scrollFrozenCols` / `scrollRightFrozenCols` 开启且对应区域存在溢出（offset > 0）时才有意义
+   */
+  scrollFrozenColsPassThroughToBody?: boolean;
+
   // /** 待实现 TODO */
   // frozenRowCount?: number;
   /** 可冻结列数，表示前多少列会出现冻结操作按钮 基本表格生效 */