Merge pull request #5100 from Erica-cod/fix/vue-dom-flicker-resize-5038

fix(vue-vtable): resolve DOM component flickering during column resize (#5038)

Author: fangsmile

packages/vue-vtable/__tests__/vue-stable-id.test.ts

@@ -0,0 +1,237 @@
+/* eslint-env jest */
+/* eslint-disable no-undef */
+// @ts-nocheck
+/**
+ * 测试 Vue DOM 组件稳定 ID 注入
+ * 对应 issue: https://github.com/VisActor/VTable/issues/5038
+ *
+ * 验证 createCustomLayout 在处理带 vue 属性的 Group 时：
+ * 1. 自动注入 cell_col_row_index 格式的稳定 ID
+ * 2. 多次调用（模拟场景图重建）产生相同 ID
+ * 3. 用户自定义 ID 不被覆盖
+ * 4. 同一 cell 内多个 vue Group 的 ID 唯一
+ */
+
+import { createCustomLayout } from '../src/utils/customLayoutUtils';
+
+// Mock VTable CustomLayout 组件
+jest.mock('@visactor/vtable', () => {
+  class MockGroup {
+    attribute: any;
+    children: any[] = [];
+    constructor(attrs: any) {
+      this.attribute = attrs;
+    }
+    add(child: any) {
+      this.children.push(child);
+    }
+    addEventListener() {}
+  }
+  return {
+    CustomLayout: {
+      Group: MockGroup,
+      Image: MockGroup,
+      Text: MockGroup,
+      Tag: MockGroup,
+      Radio: MockGroup,
+      CheckBox: MockGroup
+    }
+  };
+});
+
+// Mock vue 的 isVNode / cloneVNode
+jest.mock('vue', () => ({
+  isVNode: (val: any) => val && val.__v_isVNode === true,
+  cloneVNode: (vnode: any, extra: any) => ({ ...vnode, ...extra })
+}));
+
+function makeGroupChild(vueProps: any = {}, typeName = 'Group') {
+  return {
+    type: { name: typeName },
+    props: {
+      width: 200,
+      height: 40,
+      vue: { ...vueProps }
+    },
+    children: null
+  };
+}
+
+function makeArgs(col: number, row: number) {
+  return {
+    col,
+    row,
+    table: {
+      headerDomContainer: document.createElement('div'),
+      bodyDomContainer: document.createElement('div')
+    }
+  };
+}
+
+describe('Vue 稳定 ID 注入', () => {
+  test('应为 vue Group 注入 cell_col_row_index 格式的稳定 ID', () => {
+    const child = makeGroupChild({});
+    const args = makeArgs(3, 5);
+
+    createCustomLayout(child, false, args);
+
+    expect(child.props.vue.id).toBe('cell_3_5_0');
+  });
+
+  test('多次调用应产生相同的 ID（模拟场景图重建）', () => {
+    const args = makeArgs(2, 7);
+
+    const child1 = makeGroupChild({});
+    createCustomLayout(child1, false, args);
+
+    const child2 = makeGroupChild({});
+    createCustomLayout(child2, false, args);
+
+    expect(child1.props.vue.id).toBe(child2.props.vue.id);
+    expect(child1.props.vue.id).toBe('cell_2_7_0');
+  });
+
+  test('用户指定的 id 不应被覆盖', () => {
+    const child = makeGroupChild({ id: 'my-custom-id' });
+    const args = makeArgs(1, 1);
+
+    createCustomLayout(child, false, args);
+
+    expect(child.props.vue.id).toBe('my-custom-id');
+  });
+
+  test('同一 cell 内多个 vue Group 应有不同的稳定 ID', () => {
+    // 构造一个包含两个 vue Group 子节点的父 Group
+    const vueChild1 = makeGroupChild({});
+    const vueChild2 = makeGroupChild({});
+
+    const parentChild = {
+      type: { name: 'Group' },
+      props: { width: 400, height: 80 },
+      children: {
+        default: () => [vueChild1, vueChild2]
+      }
+    };
+
+    const args = makeArgs(4, 10);
+    createCustomLayout(parentChild, false, args);
+
+    // 两个子节点都应被注入稳定 ID
+    expect(vueChild1.props.vue.id).toBe('cell_4_10_0');
+    expect(vueChild2.props.vue.id).toBe('cell_4_10_1');
+  });
+
+  test('isHeader=true 时应使用 headerDomContainer', () => {
+    const args = makeArgs(0, 0);
+    const child = makeGroupChild({});
+
+    createCustomLayout(child, true, args);
+
+    expect(child.props.vue.container).toBe(args.table.headerDomContainer);
+    expect(child.props.vue.id).toBe('cell_0_0_0');
+  });
+
+  test('isHeader=false 时应使用 bodyDomContainer', () => {
+    const args = makeArgs(1, 3);
+    const child = makeGroupChild({});
+
+    createCustomLayout(child, false, args);
+
+    expect(child.props.vue.container).toBe(args.table.bodyDomContainer);
+  });
+});
+
+describe('VTableVueAttributePlugin 缓存命中同步渲染', () => {
+  test('renderGraphicHTML 缓存命中时应同步调用 doRenderGraphic', () => {
+    // 直接引入插件类进行行为验证
+    const { VTableVueAttributePlugin } = require('../src/components/custom/vtable-vue-attribute-plugin');
+
+    const plugin = new VTableVueAttributePlugin();
+    plugin.htmlMap = {};
+    plugin.renderId = 1;
+
+    const mockWrapContainer = document.createElement('div');
+    document.body.appendChild(mockWrapContainer);
+
+    const stableId = 'vue_cell_3_5_0';
+
+    // 预填充缓存条目
+    plugin.htmlMap[stableId] = {
+      wrapContainer: mockWrapContainer,
+      nativeContainer: document.body,
+      container: document.body,
+      renderId: 0,
+      graphic: null,
+      isInViewport: true,
+      lastPosition: null,
+      lastStyle: {}
+    };
+
+    // 追踪 doRenderGraphic 是否被同步调用
+    let doRenderCalled = false;
+    const originalDoRender = plugin.doRenderGraphic;
+    plugin.doRenderGraphic = function (graphic: any) {
+      doRenderCalled = true;
+    };
+
+    const mockGraphic = {
+      attribute: {
+        vue: {
+          id: 'cell_3_5_0',
+          element: { __v_isVNode: true },
+          container: document.body
+        }
+      },
+      stage: {
+        window: { getContainer: () => document.body },
+        AABBBounds: { x1: 0, x2: 100, y1: 0, y2: 100 }
+      },
+      globalAABBBounds: { x1: 10, x2: 50, y1: 10, y2: 50 },
+      id: null,
+      _uid: 999
+    };
+
+    plugin.renderGraphicHTML(mockGraphic);
+
+    // 缓存命中 → 同步调用 doRenderGraphic，不走 rAF
+    expect(doRenderCalled).toBe(true);
+    expect(plugin.renderQueue.size).toBe(0);
+
+    document.body.removeChild(mockWrapContainer);
+  });
+
+  test('renderGraphicHTML 无缓存时应走异步队列', () => {
+    const { VTableVueAttributePlugin } = require('../src/components/custom/vtable-vue-attribute-plugin');
+
+    const plugin = new VTableVueAttributePlugin();
+    plugin.htmlMap = {};
+    plugin.renderId = 1;
+
+    // mock scheduleRender 避免 vglobal 在 jsdom 中不可用
+    const originalSchedule = plugin.scheduleRender;
+    plugin.scheduleRender = jest.fn();
+
+    const mockGraphic = {
+      attribute: {
+        vue: {
+          id: 'cell_0_0_0',
+          element: { __v_isVNode: true },
+          container: document.body
+        }
+      },
+      stage: {
+        window: { getContainer: () => document.body },
+        AABBBounds: { x1: 0, x2: 100, y1: 0, y2: 100 }
+      },
+      globalAABBBounds: { x1: 10, x2: 50, y1: 10, y2: 50 },
+      id: null,
+      _uid: 123
+    };
+
+    plugin.renderGraphicHTML(mockGraphic);
+
+    // 无缓存 → 加入异步队列并调用 scheduleRender
+    expect(plugin.renderQueue.size).toBe(1);
+    expect(plugin.scheduleRender).toHaveBeenCalled();
+  });
+});

packages/vue-vtable/jest.config.js

@@ -0,0 +1,26 @@
+const path = require('path');
+
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'jsdom',
+  testRegex: '/__tests__(/.*)+\\.test\\.(js|ts)$',
+  silent: false,
+  verbose: true,
+  globals: {
+    'ts-jest': {
+      diagnostics: {
+        exclude: ['**']
+      },
+      tsconfig: {
+        resolveJsonModule: true,
+        esModuleInterop: true
+      }
+    },
+    __DEV__: true
+  },
+  moduleNameMapper: {
+    '@visactor/vtable$': '<rootDir>/../vtable/src/index',
+    '@visactor/vtable/es/(.*)': '<rootDir>/../vtable/src/$1'
+  },
+  setupFiles: ['./setup-mock.js']
+};

packages/vue-vtable/package.json

@@ -46,6 +46,7 @@
     "start": "vite ./demo",
     "build": "npm run fix-memory-limit && cross-env USE_TYPESCRIPT2=true bundle --clean",
     "compile": "tsc --noEmit",
+    "test": "jest --config jest.config.js",
     "eslint": "eslint --debug --fix src/",
     "fix-memory-limit": "cross-env LIMIT=10240 increase-memory-limit"
   },

packages/vue-vtable/src/components/custom/vtable-vue-attribute-plugin.ts

@@ -85,7 +85,18 @@ export class VTableVueAttributePlugin extends HtmlAttributePlugin implements IPl
     if (!this.checkNeedRender(graphic)) {
       return;
     }
-    // 加入异步渲染队列
+
+    // 缓存命中时同步渲染：立即更新 renderId，防止 clearCacheContainer 误清
+    const opts = this.getGraphicOptions(graphic);
+    if (opts) {
+      const targetMap = this.htmlMap?.[opts.id];
+      if (targetMap && this.checkDom(targetMap.wrapContainer)) {
+        this.doRenderGraphic(graphic);
+        return;
+      }
+    }
+
+    // 无缓存或 DOM 不在文档中，走异步渲染队列
     this.renderQueue.add(graphic);
     this.scheduleRender();
   }
@@ -168,6 +179,7 @@ export class VTableVueAttributePlugin extends HtmlAttributePlugin implements IPl
     // 更新样式并记录渲染 ID
     if (targetMap) {
       targetMap.renderId = this.renderId;
+      targetMap.graphic = graphic;
       targetMap.lastAccessed = Date.now();
       this.updateAccessQueue(id);
       this.updateStyleOfWrapContainer(graphic, stage, targetMap.wrapContainer, targetMap.nativeContainer);

packages/vue-vtable/src/utils/customLayoutUtils.ts

@@ -1,6 +1,6 @@
 import * as VTable from '@visactor/vtable';
 import { convertPropsToCamelCase, toCamelCase } from './stringUtils';
-import { isFunction, isObject } from '@visactor/vutils';
+import { isFunction, isNil, isObject } from '@visactor/vutils';
 import { cloneVNode, isVNode } from 'vue';
 
 // 检查属性是否为事件
@@ -10,6 +10,9 @@ function isEventProp(key: string, props: any) {
 
 // 创建自定义布局
 export function createCustomLayout(children: any, isHeader?: boolean, args?: any): any {
+  // 同一 cell 内多个 vue Group 的计数器，每次 createCustomLayout 调用时归零
+  let vueIndex = 0;
+
   // 组件映射
   const componentMap: Record<string, any> = {
     Group: VTable.CustomLayout.Group,
@@ -56,10 +59,14 @@ export function createCustomLayout(children: any, isHeader?: boolean, args?: any
         targetVNode = null;
       }
 
+      // 注入稳定 ID：基于 cell 坐标 + 递增索引，确保场景图重建后缓存 key 不变
+      const stableId = isNil((props.vue as any).id) ? `cell_${args.col}_${args.row}_${vueIndex++}` : undefined;
+
       Object.assign(child.props.vue, {
         element: targetVNode,
         // 不接入外部指定
-        container: isHeader ? args?.table?.headerDomContainer : args?.table?.bodyDomContainer
+        container: isHeader ? args?.table?.headerDomContainer : args?.table?.bodyDomContainer,
+        ...(stableId ? { id: stableId } : {})
       });
       return component;
     }

packages/vue-vtable/tscofig.eslint.json

@@ -15,6 +15,7 @@
   },
   "include": [
     "src",
-    "demo"
+    "demo",
+    "__tests__"
   ]
 }