feat: 支持自定义 G 5.0 插件和配置 (#2423)

* feat: 支持自定义 G 5.0 插件和配置移除 supportsCSSTransform, devicePixelRatio, 统一使用 transformCanvasConfig 配置 BREAKING CHANGE: 移除 devicePixelRatio 和 supportsCSSTransform * docs: 增加文档 * test: update * test: 增加单测
antvis · Nov 22, 2023 · cc6c47f · cc6c47f
1 parent e3b919a
commit cc6c47f
Show file tree

Hide file tree

Showing 30 changed files with 442 additions and 103 deletions.
diff --git a/packages/s2-core/CHANGELOG.md b/packages/s2-core/CHANGELOG.md
@@ -1,12 +1,10 @@
 # [@antv/s2-v2.0.0-next.8](https://github.com/antvis/S2/compare/@antv/s2-v2.0.0-next.7...@antv/s2-v2.0.0-next.8) (2023-07-17)
 
-
 ### Bug Fixes
 
 * 修复 meta name 同名时，hoverFocus 出错的问题 ([#2180](https://github.com/antvis/S2/issues/2180)) ([1480528](https://github.com/antvis/S2/commit/1480528c119f33fe40bc08e52e7abf87e9f9a797))
 * 修复导出数据分隔符有误的问题 ([#2241](https://github.com/antvis/S2/issues/2241)) ([ec0a31c](https://github.com/antvis/S2/commit/ec0a31c4fc660b44176b074d4cc8c098dbe95eb4))
 
-
 ### Features
 
 * 使用 requestIdleCallback 处理数据大量导出的情况 ([#2272](https://github.com/antvis/S2/issues/2272)) ([42a5551](https://github.com/antvis/S2/commit/42a55516dd369d9ab5579b52fbc9900b0ad81858))
@@ -20,7 +18,6 @@
 
 # [@antv/s2-v2.0.0-next.7](https://github.com/antvis/S2/compare/@antv/s2-v2.0.0-next.6...@antv/s2-v2.0.0-next.7) (2023-04-28)
 
-
 ### Bug Fixes
 
 * canvas mouseout 判断错误 ([#2181](https://github.com/antvis/S2/issues/2181)) ([16c0b82](https://github.com/antvis/S2/commit/16c0b824aef16d109e8db8d2fe6b3a25a413dcfa))
@@ -38,7 +35,6 @@
 * 行头过宽且不冻结时滚动条渲染错误 ([#2173](https://github.com/antvis/S2/issues/2173)) ([ab79ea0](https://github.com/antvis/S2/commit/ab79ea0664046bc6479a717d7b3b0ee7efe05b31))
 * 避免s2实例被污染 ([8c44a85](https://github.com/antvis/S2/commit/8c44a85a678eadaab3fb2a66b5b02a123f74c9bb))
 
-
 ### Features
 
 * icon支持更新name与fill ([#2138](https://github.com/antvis/S2/issues/2138)) ([d000aea](https://github.com/antvis/S2/commit/d000aeac332676cfa15d9986ec7f4be948c565d0))
@@ -56,7 +52,7 @@
 
 ### Bug Fixes
 
-* 传入 g 的 supportCSSTransform 改为 supportsCSSTransform ([7531aab](https://github.com/antvis/S2/commit/7531aab7fd12a35533d95267a818dfd3f821ece0))
+* 传入 g 的 supportsCSSTransform 改为 supportsCSSTransform ([7531aab](https://github.com/antvis/S2/commit/7531aab7fd12a35533d95267a818dfd3f821ece0))
 
 ### Features
 
@@ -989,7 +985,7 @@
 ### Features
 
 * **facet:** add scrollBarPosition option ([#997](https://github.com/antvis/S2/issues/997)) ([8937dc8](https://github.com/antvis/S2/commit/8937dc84255c68b9d5b75255263866b8c1c359aa))
-* 增加 supportCSSTransform 设置 ([#990](https://github.com/antvis/S2/issues/990)) ([be45f83](https://github.com/antvis/S2/commit/be45f83ec0bfea402fab127641264c362405d289))
+* 增加 supportsCSSTransform 设置 ([#990](https://github.com/antvis/S2/issues/990)) ([be45f83](https://github.com/antvis/S2/commit/be45f83ec0bfea402fab127641264c362405d289))
 
 # [@antv/s2-v1.5.0](https://github.com/antvis/S2/compare/@antv/s2-v1.4.0...@antv/s2-v1.5.0) (2022-01-07)
 

diff --git a/packages/s2-core/__tests__/spreadsheet/custom-cell-style-spec.ts b/packages/s2-core/__tests__/spreadsheet/custom-cell-style-spec.ts
@@ -17,8 +17,12 @@ describe('SpreadSheet Custom Cell Style Tests', () => {
   const s2Options: S2Options = {
     width: 600,
     height: 400,
-    devicePixelRatio: 1,
     hierarchyType: 'grid',
+    transformCanvasConfig() {
+      return {
+        devicePixelRatio: 1,
+      };
+    },
   };
 
   const mapNodeSize = (nodes: Node[] | ViewMeta[]) =>

diff --git a/packages/s2-core/__tests__/spreadsheet/spread-sheet-spec.ts b/packages/s2-core/__tests__/spreadsheet/spread-sheet-spec.ts
@@ -1,7 +1,7 @@
 import * as mockDataConfig from 'tests/data/simple-data.json';
-import { getContainer, sleep } from 'tests/util/helpers';
+import { createPivotSheet, getContainer, sleep } from 'tests/util/helpers';
 import { pick } from 'lodash';
-import { CanvasEvent } from '@antv/g';
+import { CanvasEvent, type CanvasContext } from '@antv/g';
 import { PivotSheet, SpreadSheet, TableSheet } from '@/sheet-type';
 import {
   DEFAULT_OPTIONS,
@@ -18,14 +18,18 @@ const s2Options: S2Options = {
 };
 
 describe('SpreadSheet Tests', () => {
+  beforeEach(() => {
+    window.devicePixelRatio = 1;
+  });
+
   describe('Mount Sheet Tests', () => {
     let container: HTMLElement;
 
-    beforeAll(() => {
+    beforeEach(() => {
       container = getContainer();
     });
 
-    afterAll(() => {
+    afterEach(() => {
       container?.remove();
     });
 
@@ -84,7 +88,11 @@ describe('SpreadSheet Tests', () => {
       async ({ devicePixelRatio }) => {
         const s2 = new PivotSheet(container, mockDataConfig, {
           ...s2Options,
-          devicePixelRatio,
+          transformCanvasConfig() {
+            return {
+              devicePixelRatio,
+            };
+          },
         });
 
         await s2.render();
@@ -103,7 +111,11 @@ describe('SpreadSheet Tests', () => {
     test('should render sheet if custom DPR less than zero', async () => {
       const s2 = new PivotSheet(container, mockDataConfig, {
         ...s2Options,
-        devicePixelRatio: 0,
+        transformCanvasConfig() {
+          return {
+            devicePixelRatio: 0,
+          };
+        },
       });
 
       await s2.render();
@@ -274,11 +286,11 @@ describe('SpreadSheet Tests', () => {
   describe('Destroy Sheet Tests', () => {
     let container: HTMLElement;
 
-    beforeAll(() => {
+    beforeEach(() => {
       container = getContainer();
     });
 
-    afterAll(() => {
+    afterEach(() => {
       container?.remove();
     });
 
@@ -427,11 +439,11 @@ describe('SpreadSheet Tests', () => {
   describe('Sheet Config Change Tests', () => {
     let container: HTMLElement;
 
-    beforeAll(() => {
+    beforeEach(() => {
       container = getContainer();
     });
 
-    afterAll(() => {
+    afterEach(() => {
       container?.remove();
     });
 
@@ -553,4 +565,67 @@ describe('SpreadSheet Tests', () => {
       });
     });
   });
+
+  describe('Custom G Canvas Plugins & Options Tests', () => {
+    test('should custom canvas options', async () => {
+      const DPR = 3;
+      const s2 = createPivotSheet({
+        ...s2Options,
+        transformCanvasConfig() {
+          return {
+            supportsCSSTransform: true,
+            devicePixelRatio: DPR,
+            cursor: 'crosshair',
+          };
+        },
+      });
+
+      await s2.render();
+
+      const { width, height } = s2.getCanvasElement();
+      const { supportsCSSTransform, devicePixelRatio, cursor } =
+        s2.container.getConfig();
+
+      expect(width).toStrictEqual(s2Options.width! * devicePixelRatio!);
+      expect(height).toStrictEqual(s2Options.height! * devicePixelRatio!);
+      expect(supportsCSSTransform).toBeTruthy();
+      expect(cursor).toEqual('crosshair');
+    });
+
+    test('should register custom canvas plugins', async () => {
+      let s2Instance = null;
+
+      const s2 = createPivotSheet({
+        ...s2Options,
+        transformCanvasConfig(renderer, spreadsheet) {
+          renderer.registerPlugin({
+            name: 'custom',
+            init: jest.fn(),
+            destroy: jest.fn(),
+            context: {} as CanvasContext,
+          });
+
+          s2Instance = spreadsheet;
+        },
+      });
+
+      await s2.render();
+
+      const { renderer } = s2.container.getConfig();
+
+      const pluginsNames = renderer?.getPlugins().map(({ name }) => name);
+
+      expect(pluginsNames).toEqual([
+        'canvas-context-register',
+        'image-loader',
+        'canvas-path-generator',
+        'canvas-renderer',
+        'dom-interaction',
+        'canvas-picker',
+        'html-renderer',
+        'custom',
+      ]);
+      expect(s2Instance).toEqual(s2);
+    });
+  });
 });
diff --git a/packages/s2-core/__tests__/unit/ui/hd-adapter/index-spec.ts b/packages/s2-core/__tests__/unit/ui/hd-adapter/index-spec.ts
@@ -13,8 +13,12 @@ describe.skip('HD Adapter Tests', () => {
   const s2Options: S2Options = {
     width: 600,
     height: 600,
-    devicePixelRatio: DPR,
     hdAdapter: true,
+    transformCanvasConfig() {
+      return {
+        devicePixelRatio: DPR,
+      };
+    },
   };
 
   let s2: SpreadSheet;

diff --git a/packages/s2-core/__tests__/unit/utils/merge-spec.ts b/packages/s2-core/__tests__/unit/utils/merge-spec.ts
@@ -1,4 +1,3 @@
-import { omit } from 'lodash';
 import type { S2DataConfig } from '@/common';
 import {
   customMerge,
@@ -177,8 +176,7 @@ describe('merge test', () => {
 
   test('should get safety options', () => {
     // 加这个测试可以防止 本地跑 demo 修改了默认配置 直接提交
-    expect(omit(getSafetyOptions(null), ['devicePixelRatio']))
-      .toMatchInlineSnapshot(`
+    expect(getSafetyOptions(null)).toMatchInlineSnapshot(`
       Object {
         "conditions": Object {},
         "cornerExtraFieldText": "",
@@ -250,7 +248,6 @@ describe('merge test', () => {
             "widthByField": null,
           },
         },
-        "supportCSSTransform": false,
         "tooltip": Object {
           "autoAdjustBoundary": "body",
           "enable": false,

diff --git a/packages/s2-core/src/common/constant/options.ts b/packages/s2-core/src/common/constant/options.ts
@@ -104,8 +104,6 @@ export const DEFAULT_OPTIONS: S2Options = {
   cornerText: '',
   cornerExtraFieldText: '',
   placeholder: EMPTY_PLACEHOLDER,
-  supportCSSTransform: false,
-  devicePixelRatio: window.devicePixelRatio,
 };
 
 const mobileWidth = document.documentElement.clientWidth;

diff --git a/packages/s2-core/src/common/interface/s2Options.ts b/packages/s2-core/src/common/interface/s2Options.ts
@@ -1,3 +1,4 @@
+import type { CanvasConfig } from '@antv/g';
 import type {
   CellCallback,
   CornerHeaderCallback,
@@ -121,20 +122,36 @@ export interface S2BasicOptions<
    */
   placeholder?: ((meta: Record<string, any>) => string) | string;
 
-  /**
-   * 是否支持 CSS 的 transform 属性
-   */
-  supportCSSTransform?: boolean;
+  // /**
+  //  * 自定义 DPR, 默认 "window.devicePixelRatio"
+  //  */
+  // devicePixelRatio?: number;
 
   /**
-   * 自定义 DPR, 默认 "window.devicePixelRatio"
+   * 设备类型: pc / mobile
    */
-  devicePixelRatio?: number;
+  device?: DeviceType;
 
   /**
-   * 设备类型: pc / mobile
+   * 自定义 AntV/G 渲染引擎配置参数 & 插件注册
+   * @see https://g.antv.antgroup.com/plugins/intro
+   * @see https://g.antv.antgroup.com/api/canvas/options
+   * @example
+    import { Plugin as PluginA11y } from '@antv/g-plugin-a11y';
+
+    transformCanvasConfig(renderer) {
+      console.log('当前已注册插件：', renderer.getPlugins(), renderer.getConfig());
+      renderer.registerPlugin(new PluginA11y({ enableExtractingText: true }));
+
+      return {
+        supportsCSSTransform: true,
+      };
+    },
    */
-  device?: DeviceType;
+  transformCanvasConfig?: (
+    renderer: CanvasConfig['renderer'],
+    spreadsheet: SpreadSheet,
+  ) => (Partial<CanvasConfig> | null | undefined) | void;
 
   /** *********** 自定义单元格 hooks **************** */
   /**

diff --git a/packages/s2-core/src/sheet-type/spread-sheet.ts b/packages/s2-core/src/sheet-type/spread-sheet.ts
@@ -4,6 +4,7 @@ import {
   FederatedPointerEvent as CanvasEvent,
   DisplayObject,
   runtime,
+  type CanvasConfig,
 } from '@antv/g';
 import { Renderer } from '@antv/g-canvas';
 import {
@@ -22,7 +23,6 @@ import {
 import { BaseCell } from '../cell';
 import {
   InterceptType,
-  MIN_DEVICE_PIXEL_RATIO,
   S2Event,
   getTooltipOperatorSortMenus,
   getTooltipOperatorTableSortMenus,
@@ -632,22 +632,17 @@ export abstract class SpreadSheet extends EE {
    * @private
    */
   protected initContainer(dom: S2MountContainer) {
-    const {
-      width,
-      height,
-      supportCSSTransform,
-      devicePixelRatio = 1,
-    } = this.options;
+    const { width, height, transformCanvasConfig } = this.options;
 
-    const renderer = new Renderer();
+    const renderer = new Renderer() as unknown as CanvasConfig['renderer'];
+    const canvasConfig = transformCanvasConfig?.(renderer, this);
 
     this.container = new Canvas({
       container: this.getMountContainer(dom) as HTMLElement,
       width,
       height,
-      devicePixelRatio: Math.max(devicePixelRatio, MIN_DEVICE_PIXEL_RATIO),
       renderer,
-      supportsCSSTransform: supportCSSTransform,
+      ...canvasConfig,
     });
 
     this.updateContainerStyle();

diff --git a/packages/s2-core/src/ui/hd-adapter/index.ts b/packages/s2-core/src/ui/hd-adapter/index.ts
@@ -100,7 +100,7 @@ export class HdAdapter {
   private renderByDevicePixelRatio = (ratio = window.devicePixelRatio) => {
     const {
       container,
-      options: { width, height, devicePixelRatio },
+      options: { width, height },
     } = this.spreadsheet;
     const canvas = this.spreadsheet.getCanvasElement();
     const lastRatio = container.getConfig().devicePixelRatio;
@@ -113,11 +113,7 @@ export class HdAdapter {
      * 缩放时, 以向上取整后的缩放比为准
      * 设备像素比改变时, 取当前和用户配置中最大的, 保证显示效果
      */
-    const pixelRatio = Math.max(
-      ratio,
-      devicePixelRatio!,
-      MIN_DEVICE_PIXEL_RATIO,
-    );
+    const pixelRatio = Math.max(ratio, lastRatio!, MIN_DEVICE_PIXEL_RATIO);
 
     // https://github.com/antvis/G/issues/1143
     container.getConfig().devicePixelRatio = pixelRatio;

diff --git a/packages/s2-react/CHANGELOG.md b/packages/s2-react/CHANGELOG.md
@@ -1,6 +1,5 @@
 # [@antv/s2-react-v2.0.0-next.7](https://github.com/antvis/S2/compare/@antv/s2-react-v2.0.0-next.6...@antv/s2-react-v2.0.0-next.7) (2023-07-17)
 
-
 ### Features
 
 * 使用 requestIdleCallback 处理数据大量导出的情况 ([#2272](https://github.com/antvis/S2/issues/2272)) ([42a5551](https://github.com/antvis/S2/commit/42a55516dd369d9ab5579b52fbc9900b0ad81858))
@@ -10,7 +9,6 @@
 * 行列头兼容 condition icon 和 action icons ([#2161](https://github.com/antvis/S2/issues/2161)) ([1df4286](https://github.com/antvis/S2/commit/1df42860f6a12d3cb182ba7633c4984a04e62890))
 * 适配g5.0异步渲染 ([#2251](https://github.com/antvis/S2/issues/2251)) ([069d03d](https://github.com/antvis/S2/commit/069d03d299429c2ffab3e20d56ecd6bb30119ffd))
 
-
 ### Performance Improvements
 
 * **react:** 防止不必要的重新渲染 ([#2275](https://github.com/antvis/S2/issues/2275)) ([f8da43d](https://github.com/antvis/S2/commit/f8da43de47761ce68ebfc0238f3e1bcb06f46bc1))
@@ -726,7 +724,7 @@
 ### Features
 
 * **facet:** add scrollBarPosition option ([#997](https://github.com/antvis/S2/issues/997)) ([8937dc8](https://github.com/antvis/S2/commit/8937dc84255c68b9d5b75255263866b8c1c359aa))
-* 增加 supportCSSTransform 设置 ([#990](https://github.com/antvis/S2/issues/990)) ([be45f83](https://github.com/antvis/S2/commit/be45f83ec0bfea402fab127641264c362405d289))
+* 增加 supportsCSSTransform 设置 ([#990](https://github.com/antvis/S2/issues/990)) ([be45f83](https://github.com/antvis/S2/commit/be45f83ec0bfea402fab127641264c362405d289))
 
 # [@antv/s2-react-v1.5.0](https://github.com/antvis/S2/compare/@antv/s2-react-v1.4.0...@antv/s2-react-v1.5.0) (2022-01-07)