Feat/component layout order

common/changes/@visactor/vtable/feat-component-layout-order_2026-01-28-11-33.json

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

common/changes/@visactor/vtable/feat-component-layout-order_2026-01-29-03-52.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "refactor: legend and title component position calculation logic #4965\n\n",
+      "type": "none",
+      "packageName": "@visactor/vtable"
+    }
+  ],
+  "packageName": "@visactor/vtable",
+  "email": "892739385@qq.com"
+}

common/changes/@visactor/vtable/feat-component-layout-order_2026-02-01-08-25.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "fix: updateOption run resize logic #4965\n\n",
+      "type": "none",
+      "packageName": "@visactor/vtable"
+    }
+  ],
+  "packageName": "@visactor/vtable",
+  "email": "892739385@qq.com"
+}

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

@@ -754,4 +754,12 @@ Default cursor style.
 
 ```
 defaultCursor?: 'default' | 'cell' | 'pointer' | 'text' | 'wait' | 'help' | 'crosshair' | 'not-allowed';
+```
+
+#${prefix} componentLayoutOrder(Array)
+
+Component layout order, default is ['legend', 'title'].
+
+```
+componentLayoutOrder?: ('legend' | 'title')[];
 ```

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

@@ -750,4 +750,12 @@ validateDragOrderOnEnd?: (source: CellAddress, target: CellAddress) => boolean;
 
 ```
 defaultCursor?: 'default' | 'cell' | 'pointer' | 'text' | 'wait' | 'help' | 'crosshair' | 'not-allowed';
+```
+
+#${prefix} componentLayoutOrder(Array)
+
+组件布局顺序，默认为 ['legend', 'title']。
+
+```
+componentLayoutOrder?: ('legend' | 'title')[];
 ```

packages/vtable/README.md

@@ -118,10 +118,30 @@ const option = {
   widthMode:'standard'
 };
 const tableInstance = new VTable.ListTable(document.getElementById(CONTAINER_ID), option);
+```
+
+## Component Layout Priority
 
+The `componentLayoutOrder` option allows you to control the layout priority of `title` and `legend`. This affects the order in which they occupy space in the drawing area. By default, the order is `['legend', 'title']`.
 
+To place the title above the legend, you can configure it as follows:
 
+```javascript
+const option = {
+  // ...other options
+  title: {
+    text: 'Sales Analysis',
+    orient: 'top',
+    align: 'center'
+  },
+  legends: {
+    orient: 'top',
+    // ...other legend options
+  },
+  componentLayoutOrder: ['title', 'legend']
+};
 
+const tableInstance = new VTable.ListTable(document.getElementById(CONTAINER_ID), option);
 ```
 
 ##

packages/vtable/examples/components/legend-title-order.ts

@@ -0,0 +1,187 @@
+import * as VTable from '../../src';
+
+const CONTAINER_ID = 'vTable';
+
+export function createTable() {
+  const records = [
+    { category: 'A', value: 120 },
+    { category: 'B', value: 90 },
+    { category: 'C', value: 60 },
+    { category: 'A', value: 120 },
+    { category: 'B', value: 90 },
+    { category: 'C', value: 60 },
+    { category: 'A', value: 120 },
+    { category: 'B', value: 90 },
+    { category: 'C', value: 60 },
+    { category: 'A', value: 120 },
+    { category: 'B', value: 90 },
+    { category: 'C', value: 60 },
+    { category: 'A', value: 120 },
+    { category: 'B', value: 90 },
+    { category: 'C', value: 60 },
+    { category: 'A', value: 120 },
+    { category: 'B', value: 90 },
+    { category: 'C', value: 60 }
+  ];
+
+  const columns: VTable.ColumnsDefine = [
+    {
+      field: 'category',
+      title: 'Category',
+      width: 120
+    },
+    {
+      field: 'value',
+      title: 'Value',
+      width: 120
+    }
+  ];
+
+  const option: VTable.ListTableConstructorOptions = {
+    container: document.getElementById(CONTAINER_ID),
+    records,
+    columns,
+    // place title and legend both at the top
+    title: {
+      text: 'Title above legend (componentLayoutOrder)',
+      orient: 'top',
+      align: 'center'
+    },
+    legends: [
+      {
+        type: 'discrete',
+        orient: 'top',
+        position: 'start',
+        data: [
+          {
+            label: 'A',
+            shape: {
+              fill: '#1664FF',
+              symbolType: 'circle'
+            }
+          },
+          {
+            label: 'B',
+            shape: {
+              fill: '#1AC6FF',
+              symbolType: 'square'
+            }
+          },
+          {
+            label: 'C',
+            shape: {
+              fill: '#FFCC00',
+              symbolType: 'triangle'
+            }
+          }
+        ]
+      },
+      {
+        type: 'discrete',
+        orient: 'top',
+        position: 'start',
+        data: [
+          {
+            label: 'A11',
+            shape: {
+              fill: '#1664FF',
+              symbolType: 'circle'
+            }
+          },
+          {
+            label: 'B',
+            shape: {
+              fill: '#1AC6FF',
+              symbolType: 'square'
+            }
+          },
+          {
+            label: 'C',
+            shape: {
+              fill: '#FFCC00',
+              symbolType: 'triangle'
+            }
+          }
+        ]
+      }
+    ]
+    // ensure title is laid out before legend so legend appears under the title
+    // componentLayoutOrder: ['title', 'legend']
+  };
+
+  const tableInstance = new VTable.ListTable(option);
+  (window as any).tableInstance = tableInstance;
+  setTimeout(() => {
+    tableInstance.updateOption({
+      container: document.getElementById(CONTAINER_ID),
+      records,
+      columns,
+      // place title and legend both at the top
+      title: {
+        text: 'Title above legend (componentLayoutOrder)',
+        orient: 'top',
+        align: 'center'
+      },
+      legends: [
+        {
+          type: 'discrete',
+          orient: 'top',
+          position: 'start',
+          data: [
+            {
+              label: 'A',
+              shape: {
+                fill: '#1664FF',
+                symbolType: 'circle'
+              }
+            },
+            {
+              label: 'B',
+              shape: {
+                fill: '#1AC6FF',
+                symbolType: 'square'
+              }
+            },
+            {
+              label: 'C',
+              shape: {
+                fill: '#FFCC00',
+                symbolType: 'triangle'
+              }
+            }
+          ]
+        },
+        {
+          type: 'discrete',
+          orient: 'top',
+          position: 'start',
+          data: [
+            {
+              label: 'A11',
+              shape: {
+                fill: '#1664FF',
+                symbolType: 'circle'
+              }
+            },
+            {
+              label: 'B',
+              shape: {
+                fill: '#1AC6FF',
+                symbolType: 'square'
+              }
+            },
+            {
+              label: 'C',
+              shape: {
+                fill: '#FFCC00',
+                symbolType: 'triangle'
+              }
+            }
+          ]
+        }
+      ],
+      // ensure title is laid out before legend so legend appears under the title
+      componentLayoutOrder: ['title', 'legend']
+    });
+  }, 4000);
+}

packages/vtable/examples/menu.ts

@@ -1073,6 +1073,10 @@ export const menus = [
       {
         path: 'components',
         name: 'size'
+      },
+      {
+        path: 'components',
+        name: 'legend-title-order'
       }
     ]
   },

packages/vtable/src/ListTable.ts

@@ -179,12 +179,15 @@ export class ListTable extends BaseTable implements ListTableAPI {
       const ListTreeStickCellPlugin = Factory.getComponent('listTreeStickCellPlugin') as IListTreeStickCellPlugin;
       this.listTreeStickCellPlugin = new ListTreeStickCellPlugin(this);
     }
+    // 首次布局同样通过 BaseTable.resize() 完成，遵循 componentLayoutOrder 中的 title/legend 优先级
+    this.resize();
     //为了确保用户监听得到这个事件 这里做了异步 确保vtable实例已经初始化完成
     setTimeout(() => {
       if (this.isReleased) {
         return;
       }
-      this.resize();
+      // // 首次布局同样通过 BaseTable.resize() 完成，遵循 componentLayoutOrder 中的 title/legend 优先级
+      // this.resize(); 注释掉这里为解决有组件的情况下 异步导致的布局抖动问题,所以把resize提到了setTimeout之前。但是原先在setTimeout中可能是为了scrollBar布局，但提到前面测试了下好像没有什么问题！后续看观察scrollBar
       this.fireListeners(TABLE_EVENT_TYPE.INITIALIZED, null);
     }, 0);
   }
@@ -708,7 +711,7 @@ export class ListTable extends BaseTable implements ListTableAPI {
     if (options.title) {
       const Title = Factory.getComponent('title') as ITitleComponent;
       internalProps.title = new Title(options.title, this);
-      this.scenegraph.resize();
+      // this.scenegraph.resize();//下面有个resize了 所以这个可以去掉
     }
     if (this.options.emptyTip) {
       if (this.internalProps.emptyTip) {
@@ -720,7 +723,11 @@ export class ListTable extends BaseTable implements ListTableAPI {
       }
     }
     this.pluginManager.updatePlugins(options.plugins);
+    // 首次布局同样通过 BaseTable.resize() 完成，遵循 componentLayoutOrder 中的 title/legend 优先级
+    this.resize();
     setTimeout(() => {
+      // // 首次布局同样通过 BaseTable.resize() 完成，遵循 componentLayoutOrder 中的 title/legend 优先级
+      // this.resize();
       this.fireListeners(TABLE_EVENT_TYPE.UPDATED, null);
     }, 0);
     return new Promise(resolve => {
@@ -1476,9 +1483,21 @@ export class ListTable extends BaseTable implements ListTableAPI {
     this.stateManager.updateHoverPos(oldHoverState.col, oldHoverState.row);
 
     this._updateSize();
-    if (this.internalProps.title && !this.internalProps.title.isReleased) {
-      this.internalProps.title.resize();
-    }
+    // if (this.internalProps.title && !this.internalProps.title.isReleased) {
+    //   this.internalProps.title.resize();
+    // }
+    // 组件布局优先级仅影响 title/legend 的布局与可用绘制区域缩减顺序
+    const layoutOrder = this.options.componentLayoutOrder ?? ['legend', 'title'];
+    layoutOrder.forEach(component => {
+      if (component === 'legend') {
+        this.internalProps.legends?.forEach(legend => {
+          legend?.resize();
+        });
+      } else if (component === 'title') {
+        this.internalProps.title?.resize();
+      }
+    });
+
     this.scenegraph.resize();
 
     if (this.options.emptyTip) {