Feat/frozen column scroll

common/changes/@visactor/vtable/feat-frozenColumn_scroll_2026-03-20-11-09.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "feat: add option scrollFrozenCols\n\n",
+      "type": "none",
+      "packageName": "@visactor/vtable"
+    }
+  ],
+  "packageName": "@visactor/vtable",
+  "email": "892739385@qq.com"
+}

docs/assets/demo/en/interaction/scroll-frozen.md

@@ -0,0 +1,62 @@
+---
+category: examples
+group: Interaction
+title: Scrollbars In Frozen Areas
+cover: https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/VTable/preview/scroll-frozen.gif
+link: interaction/scroll-frozen
+option: ListTable#scrollFrozenCols
+---
+
+# Scrollbars In Frozen Areas
+
+This example shows horizontal scrolling inside frozen areas (both left and right) when the total width of frozen columns exceeds the maximum frozen width.
+
+## Key Options
+
+- `frozenColCount` / `rightFrozenColCount` set left/right frozen columns count
+- `maxFrozenWidth` / `maxRightFrozenWidth` set the maximum frozen area width
+- `scrollFrozenCols` / `scrollRightFrozenCols` enable horizontal scrolling inside frozen areas
+- `theme.scrollStyle.visible` can be used to observe scrollbar visibility behavior across multiple scrollable regions (e.g. `scrolling` / `focus`)
+
+## Code
+
+```javascript livedemo template=vtable
+let tableInstance;
+fetch('https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/VTable/North_American_Superstore_data.json')
+  .then(res => res.json())
+  .then(data => {
+    const columns = [
+      { field: 'Order ID', title: 'Order ID', width: 160 },
+      { field: 'Customer ID', title: 'Customer ID', width: 160 },
+      { field: 'Product Name', title: 'Product Name', width: 220 },
+      { field: 'Category', title: 'Category', width: 140 },
+      { field: 'Sub-Category', title: 'Sub-Category', width: 160 },
+      { field: 'Region', title: 'Region', width: 120 },
+      { field: 'City', title: 'City', width: 140 },
+      { field: 'Order Date', title: 'Order Date', width: 140 },
+      { field: 'Region', title: 'Region', width: 120 },
+      { field: 'City', title: 'City', width: 140 },
+      { field: 'Order Date', title: 'Order Date', width: 140 },
+      { field: 'Quantity', title: 'Quantity', width: 120 },
+      { field: 'Sales', title: 'Sales', width: 120 },
+      { field: 'Profit', title: 'Profit', width: 120 },
+      { field: 'Segment', title: 'Segment', width: 140 },
+      { field: 'Ship Mode', title: 'Ship Mode', width: 140 }
+    ];
+
+    const option = {
+      records: data,
+      columns,
+      widthMode: 'standard',
+      frozenColCount: 4,
+      rightFrozenColCount: 4,
+      maxFrozenWidth: 320,
+      maxRightFrozenWidth: 320,
+      scrollFrozenCols: true,
+      scrollRightFrozenCols: true,
+      overscrollBehavior: 'none'
+    };
+    tableInstance = new VTable.ListTable(document.getElementById(CONTAINER_ID), option);
+    window['tableInstance'] = tableInstance;
+  });
+```

docs/assets/demo/menu.json

@@ -439,8 +439,7 @@
             "zh": "甘特图缩放滚动条",
             "en": "Gantt DataZoomAxis Scrollbar"
           }
-        }
-        ,
+        },
         {
           "path": "gantt-baseline",
           "title": {
@@ -920,6 +919,13 @@
             "en": "scroll"
           }
         },
+        {
+          "path": "scroll-frozen",
+          "title": {
+            "zh": "冻结区可滚动",
+            "en": "Scroll frozen area"
+          }
+        },
         {
           "path": "arrowkeys-move-select",
           "title": {
@@ -1845,4 +1851,4 @@
       ]
     }
   ]
-}
+}

docs/assets/demo/zh/interaction/scroll-frozen.md

@@ -0,0 +1,62 @@
+---
+category: examples
+group: Interaction
+title: 冻结区域滚动条
+cover: https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/VTable/preview/scroll-frozen.gif
+link: interaction/scroll-frozen
+option: ListTable#scrollFrozenCols
+---
+
+# 冻结区域滚动条
+
+该示例展示了当冻结区域的列宽总和超过最大冻结宽度时，开启冻结区域内部横向滚动的效果（左冻结与右冻结）。
+
+## 关键配置
+
+- `frozenColCount` / `rightFrozenColCount` 设置左右冻结列数
+- `maxFrozenWidth` / `maxRightFrozenWidth` 设置左右冻结区域最大宽度
+- `scrollFrozenCols` / `scrollRightFrozenCols` 开启冻结区域内部横向滚动
+- `theme.scrollStyle.visible` 可配合观察滚动条在多滚动区域下的显隐行为（如 `scrolling` / `focus`）
+
+## 代码演示
+
+```javascript livedemo template=vtable
+let tableInstance;
+fetch('https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/VTable/North_American_Superstore_data.json')
+  .then(res => res.json())
+  .then(data => {
+    const columns = [
+      { field: 'Order ID', title: 'Order ID', width: 160 },
+      { field: 'Customer ID', title: 'Customer ID', width: 160 },
+      { field: 'Product Name', title: 'Product Name', width: 220 },
+      { field: 'Category', title: 'Category', width: 140 },
+      { field: 'Sub-Category', title: 'Sub-Category', width: 160 },
+      { field: 'Region', title: 'Region', width: 120 },
+      { field: 'City', title: 'City', width: 140 },
+      { field: 'Order Date', title: 'Order Date', width: 140 },
+      { field: 'Region', title: 'Region', width: 120 },
+      { field: 'City', title: 'City', width: 140 },
+      { field: 'Order Date', title: 'Order Date', width: 140 },
+      { field: 'Quantity', title: 'Quantity', width: 120 },
+      { field: 'Sales', title: 'Sales', width: 120 },
+      { field: 'Profit', title: 'Profit', width: 120 },
+      { field: 'Segment', title: 'Segment', width: 140 },
+      { field: 'Ship Mode', title: 'Ship Mode', width: 140 }
+    ];
+
+    const option = {
+      records: data,
+      columns,
+      widthMode: 'standard',
+      frozenColCount: 4,
+      rightFrozenColCount: 4,
+      maxFrozenWidth: 320,
+      maxRightFrozenWidth: 320,
+      scrollFrozenCols: true,
+      scrollRightFrozenCols: true,
+      overscrollBehavior: 'none'
+    };
+    tableInstance = new VTable.ListTable(document.getElementById(CONTAINER_ID), option);
+    window['tableInstance'] = tableInstance;
+  });
+```

docs/assets/guide/en/basic_function/frozen_column_row.md

@@ -7,13 +7,13 @@ Note: This function is only supported in the basic table ListTable.
 ## Set Left Frozen Columns
 
 Freezing the left column is the most common freezing requirement. Compared with the freezing in other directions, this is also the most comprehensive freezing ability supported by VTable.
-f
 The relevant configuration items are as follows:
 
 - `frozenColCount`: Number of frozen columns, default is 0.
 - `allowFrozenColCount`: Number of columns allowed to be operated, that is, the number of columns before which the freeze operation button will appear, default is 0.
 - `showFrozenIcon`: Whether to display the fixed column icon, default is `true`.
 - `maxFrozenWidth`: Maximum freeze width, default is '80%'.
+- `scrollFrozenCols`: When the total width of frozen columns exceeds `maxFrozenWidth`, the left frozen area becomes horizontally scrollable, default is `false`. When enabled, all frozen columns are kept and you can use trackpad horizontal scrolling or drag the scrollbar inside the frozen area.
 - `unfreezeAllOnExceedsMaxWidth`: When the column width exceeds the maximum freeze width, whether to automatically unfreeze all, default 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.
 
 Here is a configuration example:
@@ -36,6 +36,29 @@ A common scenario for freezing the right column in a table is to place operation
 The configuration items are as follows:
 
 - `rightFrozenColCount`: Number of right frozen columns, default is 0.
+- `maxRightFrozenWidth`: Maximum freeze width for right frozen columns (fixed value or percentage). Defaults to `maxFrozenWidth`.
+- `scrollRightFrozenCols`: When the total width of right frozen columns exceeds `maxRightFrozenWidth`, the right frozen area becomes horizontally scrollable, default is `false`.
+
+## Horizontal Scrolling Inside Frozen Areas
+
+When the frozen area's content width exceeds the maximum freeze width, you can enable horizontal scrolling inside the frozen area to keep all frozen columns.
+
+```javascript
+const listTable = new ListTable({
+  // ...other configuration items
+  frozenColCount: 6,
+  maxFrozenWidth: 320,
+  scrollFrozenCols: true,
+
+  rightFrozenColCount: 4,
+  maxRightFrozenWidth: 320,
+  scrollRightFrozenCols: true
+});
+```
+
+After enabling:
+- The left/right frozen areas respond to trackpad horizontal scrolling within their own regions.
+- When scrollbars are visible, independent horizontal scrollbars for frozen areas will appear at the bottom.
 
 ## Set Top Frozen Rows
 

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

@@ -21,6 +21,12 @@ VTable provides rich scroll style configuration items, and users can customize t
 - barToSide: Whether to display to the edge of the container even though the contents are not full. Default false
 - ignoreFrozenCols: Ignore the width of frozen columns, default false
 
+When horizontal scrolling inside frozen areas is enabled (for example `scrollFrozenCols` / `scrollRightFrozenCols`), there may be multiple horizontal scrollable regions (body / left frozen / right frozen). In this case:
+
+- `visible: 'always'`: Scrollbars of all regions are always visible (only if the region is actually scrollable).
+- `visible: 'scrolling'`: Scrollbars are shown when scrolling happens or when hovering over the scrollbar area, and will auto-hide after leaving.
+- `visible: 'focus'`: Only the scrollbar of the region under the pointer is shown (to avoid multiple scrollbars showing at the same time).
+
 Below we show the effect of these configurations with an example:
 
 ```javascript livedemo  template=vtable
@@ -109,6 +115,33 @@ fetch('https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/VTable/North_American
 
 VTable supports horizontal scrolling while holding down the Shift key, or directly dragging the horizontal scroll bar to make it easier for users to browse table data. Of course, if your computer has a touchpad, you can swipe left and right directly on the touchpad to achieve horizontal scrolling.
 
+## Horizontal scrolling inside frozen areas
+
+After enabling frozen columns, if the frozen area's total frozen width exceeds the maximum frozen width (`maxFrozenWidth` / `maxRightFrozenWidth`), besides auto-unfreezing columns to fit the viewport, you can enable horizontal scrolling inside frozen areas to keep all frozen columns:
+
+- Left frozen area: enable with `scrollFrozenCols: true`
+- Right frozen area: enable with `scrollRightFrozenCols: true`
+
+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
+const option = {
+  // ...other configuration items
+  frozenColCount: 6,
+  maxFrozenWidth: 320,
+  scrollFrozenCols: true,
+
+  rightFrozenColCount: 4,
+  maxRightFrozenWidth: 320,
+  scrollRightFrozenCols: true,
+  scrollFrozenColsPassThroughToBody: false
+};
+```
+
 ## scroll interface
 
 VTable provides the scrollToCell interface for scrolling to the specified cell location. The method accepts the cellAddr parameter to specify the cell location to scroll to. Example code is as follows:

docs/assets/guide/zh/basic_function/frozen_column_row.md

@@ -7,13 +7,13 @@
 ## 左侧冻结列设置
 
 针对左侧列冻结是最常见的冻结需求，相比其他方向的冻结这也是 VTable 支持功能最全面的冻结能力。
-f
 相关配置项如下：
 
 - `frozenColCount`: 冻结列数，默认为 0。
 - `allowFrozenColCount`: 允许可操作冻结列数，即前多少列会出现冻结操作按钮，默认为 0。
 - `showFrozenIcon`: 是否显示固定列图标，默认为 `true`。
 - `maxFrozenWidth`: 最大冻结宽度，默认为'80%'。
+- `scrollFrozenCols`: 当冻结列总宽度超过 `maxFrozenWidth` 时，左侧冻结区域可横向滚动，默认为 `false`。开启后会保留全部冻结列，并在冻结区域内通过触摸板横向滚动或拖拽滚动条查看超出部分。
 - `unfreezeAllOnExceedsMaxWidth`: 当列宽超过最大冻结宽度时，是否全部自动解冻，默认为 `true`。如果设置为false，则不会解冻全部列，而是根据 maxFrozenWidth 的值来决定最终解冻的列数。
 
 以下是一个配置示例：
@@ -36,6 +36,29 @@ const listTable = new ListTable({
 配置项如下：
 
 - `rightFrozenColCount`: 右侧冻结列数，默认为 0。
+- `maxRightFrozenWidth`: 右侧最大冻结宽度，固定值 or 百分比。默认与 `maxFrozenWidth` 一致。
+- `scrollRightFrozenCols`: 当右侧冻结列总宽度超过 `maxRightFrozenWidth` 时，右侧冻结区域可横向滚动，默认为 `false`。
+
+## 冻结区域横向滚动
+
+当冻结区域的“内容总宽度”超过最大冻结宽度时，可以开启冻结区域内部横向滚动来保留全部冻结列。
+
+```javascript
+const listTable = new ListTable({
+  // ...其他配置项
+  frozenColCount: 6,
+  maxFrozenWidth: 320,
+  scrollFrozenCols: true,
+
+  rightFrozenColCount: 4,
+  maxRightFrozenWidth: 320,
+  scrollRightFrozenCols: true
+});
+```
+
+开启后：
+- 左/右冻结区域会在自身区域内响应触摸板横向滚动。
+- 当滚动条可见时，底部会出现对应冻结区域的独立横向滚动条。
 
 ## 顶部冻结行
 

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

@@ -21,6 +21,12 @@ VTable 提供了丰富的滚动样式配置项，用户可以按照自己的需
 - barToSide ：是否显示到容器的边缘 尽管内容没有撑满的情况下. 默认 false
 - ignoreFrozenCols ：横向滚动条是否忽略冻结列宽度，默认false
 
+当表格启用了冻结区域内部横向滚动（如 `scrollFrozenCols` / `scrollRightFrozenCols`）时，表格横向会同时存在多个可滚动区域（body / 左冻结 / 右冻结）。此时：
+
+- `visible: 'always'`：所有区域的滚动条都会常驻显示（若该区域确实可滚动）。
+- `visible: 'scrolling'`：仅在“滚动发生”或“鼠标悬停在滚动条区域”时显示，离开后会自动隐藏。
+- `visible: 'focus'`：鼠标指针聚焦到某个区域时，仅显示该区域对应的滚动条（避免多个滚动条同时展示）。
+
 下面我们通过示例来展示这些配置的效果：
 
 ```javascript livedemo   template=vtable
@@ -109,6 +115,35 @@ fetch('https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/VTable/North_American
 
 VTable 支持在按住 Shift 键时进行横向滚动，或者直接拖拽横向滚动条，以便用户更方便地浏览表格数据。当然，如果您的电脑有触摸板，可以直接在触摸板上直接左右滑动来实现横向滚动。
 
+## 冻结区域内横向滚动
+
+在开启列冻结后，如果冻结区域的“冻结列总宽度”超过最大冻结宽度（`maxFrozenWidth` / `maxRightFrozenWidth`），除了将冻结列自动解冻以适配可视宽度外，也可以开启冻结区域内部横向滚动来“保留全部冻结列”：
+
+- 左侧冻结区域：通过 `scrollFrozenCols: true` 开启
+- 右侧冻结区域：通过 `scrollRightFrozenCols: true` 开启
+
+开启后，触摸板的横向滚动会在对应冻结区域内生效（无需先滚动 body），并且在滚动条可见时底部会出现对应冻结区域的独立横向滚动条，支持拖拽滑块或点击轨道进行滚动。
+
+默认情况下（`scrollFrozenColsPassThroughToBody: false`），在冻结区域滚动到头/尾时不会联动滚动 body；如希望在冻结区域到边界后继续滚动 body，可开启该配置。
+
+示例：
+
+```javascript
+const option = {
+  // ...其他配置项
+  frozenColCount: 6,
+  maxFrozenWidth: 320,
+  scrollFrozenCols: true,
+
+  rightFrozenColCount: 4,
+  maxRightFrozenWidth: 320,
+  scrollRightFrozenCols: true,
+  scrollFrozenColsPassThroughToBody: false
+};
+```
+
+更多冻结相关配置可参考《行列冻结》章节。
+
 ## 滚动接口
 
 VTable 提供了 scrollToCell 接口，用于滚到指定的单元格位置。该方法接受 cellAddr 参数用于指定要滚动到的单元位置。示例代码如下：

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

@@ -104,6 +104,22 @@ number of frozen rows at the bottom
 
 Maximum freezing width, fixed value or percentage. Default is '80%'
 
+#${prefix} scrollFrozenCols(boolean) = false
+
+When the total width of frozen columns exceeds maxFrozenWidth, the frozen area becomes horizontally scrollable. When enabled, all 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} maxRightFrozenWidth(number | string) = maxFrozenWidth
+
+Maximum freeze width for right frozen columns (fixed value or percentage). Defaults to maxFrozenWidth.
+
+#${prefix} scrollRightFrozenCols(boolean) = false
+
+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.
@@ -762,4 +778,4 @@ Component layout order, default is ['legend', 'title'].
 
 ```
 componentLayoutOrder?: ('legend' | 'title')[];
-```
+```