fix: 修复导出 CSV 时分隔符错误导致的展示格式错误 close #2701

BREAKING CHANGE: Export 组件 和 asyncGetAllPlainData, copyToClipboard
的是否异步导出参数统一为 async

packages/s2-core/__tests__/bugs/issue-446-spec.ts

@@ -6,7 +6,7 @@
  */
 import { getContainer } from '../util/helpers';
 import * as mockDataConfig from '../data/data-issue-446.json';
-import type { S2Options } from '../../src';
+import { TAB_SEPARATOR, type S2Options } from '../../src';
 import { TableSheet } from '@/sheet-type';
 import { asyncGetAllPlainData } from '@/utils';
 
@@ -25,7 +25,7 @@ describe('export', () => {
     await s2.render();
     const data = await asyncGetAllPlainData({
       sheetInstance: s2,
-      split: '\t',
+      split: TAB_SEPARATOR,
       formatOptions: true,
     });
 
@@ -50,7 +50,7 @@ describe('export', () => {
     await s2.render();
     const data = await asyncGetAllPlainData({
       sheetInstance: s2,
-      split: '\t',
+      split: TAB_SEPARATOR,
     });
 
     expect(data.split('\n').length).toEqual(3);

packages/s2-core/__tests__/bugs/issue-565-spec.ts

@@ -6,7 +6,7 @@
  */
 import * as mockDataConfig from 'tests/data/data-issue-565.json';
 import { getContainer } from 'tests/util/helpers';
-import type { S2Options } from '../../src';
+import { TAB_SEPARATOR, type S2Options } from '../../src';
 import { PivotSheet } from '@/sheet-type';
 import { asyncGetAllPlainData } from '@/utils';
 
@@ -24,7 +24,7 @@ describe('Export data in pivot tree mode', () => {
 
     const data = await asyncGetAllPlainData({
       sheetInstance: s2,
-      split: '\t',
+      split: TAB_SEPARATOR,
     });
     const rows = data.split('\n');
 

packages/s2-core/__tests__/unit/utils/export/__snapshots__/export-pivot-spec.ts.snap

@@ -44,8 +44,8 @@ province	city	number	number	number	number
 
 exports[`PivotSheet Export Test should export correct data in grid mode with totals in col 1`] = `
 "	类别	家具	家具	家具	办公用品	办公用品	办公用品	总计
-	子类别	桌子	沙发	小计	笔	纸张	小计	
-省份	城市	数量	数量		数量	数量		
+	子类别	桌子	沙发	小计	笔	纸张	小计
+省份	城市	数量	数量		数量	数量
 浙江省	杭州市	7789	5343	13132	945	1343	2288	15420
 浙江省	绍兴市	2367	632	2999	1304	1354	2658	5657
 浙江省	宁波市	3877	7234	11111	1145	1523	2668	13779
@@ -61,7 +61,7 @@ exports[`PivotSheet Export Test should export correct data in grid mode with tot
 
 exports[`PivotSheet Export Test should export correct data in grid mode with totals in row 1`] = `
 "	类别		家具	家具	家具	办公用品	办公用品	办公用品	总计
-	子类别		桌子	沙发	小计	笔	纸张	小计	
+	子类别		桌子	沙发	小计	笔	纸张	小计
 浙江省	杭州市	数量	7789	5343	13132	945	1343	2288	15420
 浙江省	绍兴市	数量	2367	632	2999	1304	1354	2658	5657
 浙江省	宁波市	数量	3877	7234	11111	1145	1523	2668	13779
@@ -148,11 +148,11 @@ exports[`PivotSheet Export Test should export correct data when data is incomple
 "	province	浙江省	浙江省	浙江省	浙江省	四川省	四川省	四川省	四川省
 	city	杭州市	绍兴市	宁波市	舟山市	成都市	绵阳市	南充市	乐山市
 type	sub_type	number	number	number	number	number	number	number	number
-家具									
+家具
 家具	桌子		2367	3877	4342	1723	1822	1943	2330
 家具	沙发		632	7234	834	2451	2244	2333	2445
-办公用品									
-办公用品	笔								
+办公用品
+办公用品	笔
 办公用品	纸张		1354	1523	1634	4004	3077	3551	352"
 `;
 
@@ -214,9 +214,9 @@ province	city	数值	数值	数值	数值
 
 exports[`PivotSheet Export Test should export correct data with formatter for custom column headers 1`] = `
 "	自定义节点 a-1	自定义节点 a-1	自定义节点 a-1	自定义节点 a-1	自定义节点 a-2
-	自定义节点 a-2	自定义节点 a-1-1	自定义节点 a-1-1	自定义节点 a-1-2	
-type	sub_type	指标1	指标2		
-家具	桌子	13	2		
+	自定义节点 a-2	自定义节点 a-1-1	自定义节点 a-1-1	自定义节点 a-1-2
+type	sub_type	指标1	指标2
+家具	桌子	13	2
 家具	椅子	11	8		"
 `;
 
@@ -225,19 +225,19 @@ exports[`PivotSheet Export Test should export correct data with formatter for cu
 自定义节点 a-1	自定义节点 a-1-1	指标1	桌子	椅子
 自定义节点 a-1	自定义节点 a-1-1	指标1	13	11
 自定义节点 a-1	自定义节点 a-1-1	指标2	2	8
-自定义节点 a-1	自定义节点 a-1-2			
+自定义节点 a-1	自定义节点 a-1-2
 自定义节点 a-2				"
 `;
 
-exports[`PivotSheet Export Test should export correctly data for single row data by { isAsyncExport: false } 1`] = `
+exports[`PivotSheet Export Test should export correctly data for single row data by { async: false } 1`] = `
 Array [
   "	type	笔	笔",
   "province	city	price	cost",
   "浙江	义乌	1	2",
 ]
 `;
 
-exports[`PivotSheet Export Test should export correctly data for single row data by { isAsyncExport: true } 1`] = `
+exports[`PivotSheet Export Test should export correctly data for single row data by { async: true } 1`] = `
 Array [
   "	type	笔	笔",
   "province	city	price	cost",

packages/s2-core/__tests__/unit/utils/export/__snapshots__/export-table-spec.ts.snap

@@ -278,14 +278,14 @@ exports[`TableSheet Export Test should export correct data with totals 1`] = `
 浙江省-province	家具-type	沙发	5343"
 `;
 
-exports[`TableSheet Export Test should export correctly data for single row data by { isAsyncExport: false } 1`] = `
+exports[`TableSheet Export Test should export correctly data for single row data by { async: false } 1`] = `
 Array [
   "province	city	type	price	cost",
   "浙江	杭州	笔	1	",
 ]
 `;
 
-exports[`TableSheet Export Test should export correctly data for single row data by { isAsyncExport: true } 1`] = `
+exports[`TableSheet Export Test should export correctly data for single row data by { async: true } 1`] = `
 Array [
   "province	city	type	price	cost",
   "浙江	杭州	笔	1	",

packages/s2-core/__tests__/unit/utils/export/export-pivot-spec.ts

@@ -10,6 +10,7 @@ import {
 } from '../../../data/custom-grid-simple-fields';
 import { CustomGridData } from '../../../data/data-custom-grid';
 import { expectMatchSnapshot } from '../../../util/helpers';
+import { CSV_SEPARATOR, TAB_SEPARATOR } from '../../../../src/common/constant';
 import { CopyMIMEType } from '@/common/interface/export';
 
 describe('PivotSheet Export Test', () => {
@@ -51,7 +52,7 @@ describe('PivotSheet Export Test', () => {
       sheetInstance: s2,
       split: NewTab,
       formatOptions: true,
-      isAsyncExport: true,
+      async: true,
     });
 
     expect(asyncData).toMatchSnapshot();
@@ -84,7 +85,7 @@ describe('PivotSheet Export Test', () => {
       sheetInstance: s2,
       split: NewTab,
       formatOptions: true,
-      isAsyncExport: true,
+      async: true,
     });
 
     expect(asyncData).toMatchSnapshot();
@@ -356,7 +357,7 @@ describe('PivotSheet Export Test', () => {
   it('should export correct data When the split separator is configured', async () => {
     const data = await asyncGetAllPlainData({
       sheetInstance: pivotSheet,
-      split: ',',
+      split: CSV_SEPARATOR,
       formatOptions: {
         formatHeader: true,
       },
@@ -392,7 +393,7 @@ describe('PivotSheet Export Test', () => {
   });
 
   // https://github.com/antvis/S2/issues/2681
-  it.each([{ isAsyncExport: false }, { isAsyncExport: true }])(
+  it.each([{ async: false }, { async: true }])(
     'should export correctly data for single row data by %o',
     async (options) => {
       const sheet = createPivotSheet({ width: 600, height: 400 });
@@ -404,7 +405,7 @@ describe('PivotSheet Export Test', () => {
       await sheet.render();
       const data = await asyncGetAllPlainData({
         sheetInstance: sheet,
-        split: '\t',
+        split: TAB_SEPARATOR,
         ...options,
       });
 

packages/s2-core/__tests__/unit/utils/export/export-table-spec.ts

@@ -7,7 +7,13 @@ import {
   expectMatchSnapshot,
   getContainer,
 } from '../../../util/helpers';
-import { FormatOptions, S2DataConfig, S2Options } from '../../../../src';
+import {
+  CSV_SEPARATOR,
+  FormatOptions,
+  S2DataConfig,
+  S2Options,
+  TAB_SEPARATOR,
+} from '../../../../src';
 import { customColSimpleColumns } from '../../../data/custom-table-col-fields';
 import { NewLine, NewTab } from '@/common';
 import { CopyMIMEType } from '@/common/interface/export';
@@ -132,7 +138,7 @@ describe('TableSheet Export Test', () => {
       formatOptions: {
         formatHeader: true,
       },
-      isAsyncExport: true,
+      async: true,
     });
 
     testCase(asyncData);
@@ -257,7 +263,7 @@ describe('TableSheet Export Test', () => {
     await tableSheet.render();
     const data = await asyncGetAllPlainData({
       sheetInstance: tableSheet,
-      split: ',',
+      split: CSV_SEPARATOR,
       formatOptions: true,
     });
     // 只取前10行数据
@@ -307,7 +313,7 @@ describe('TableSheet Export Test', () => {
     await tableSheet.render();
     const data = await asyncGetAllPlainData({
       sheetInstance: tableSheet,
-      split: ',',
+      split: CSV_SEPARATOR,
       formatOptions: {
         formatHeader: true,
       },
@@ -352,7 +358,7 @@ describe('TableSheet Export Test', () => {
     await tableSheet.render();
     const data = await asyncGetAllPlainData({
       sheetInstance: tableSheet,
-      split: ',',
+      split: CSV_SEPARATOR,
       formatOptions: {
         formatHeader: true,
       },
@@ -362,7 +368,7 @@ describe('TableSheet Export Test', () => {
   });
 
   // https://github.com/antvis/S2/issues/2681
-  it.each([{ isAsyncExport: false }, { isAsyncExport: true }])(
+  it.each([{ async: false }, { async: true }])(
     'should export correctly data for single row data by %o',
     async (options) => {
       const tableSheet = createTableSheet({ width: 600, height: 400 });
@@ -377,7 +383,7 @@ describe('TableSheet Export Test', () => {
       await tableSheet.render();
       const data = await asyncGetAllPlainData({
         sheetInstance: tableSheet,
-        split: '\t',
+        split: TAB_SEPARATOR,
         ...options,
       });
 

packages/s2-core/__tests__/util/helpers.ts

@@ -22,6 +22,7 @@ import {
   EventController,
   FormatOptions,
   asyncGetAllPlainData,
+  TAB_SEPARATOR,
 } from '../../src';
 
 import { assembleOptions, assembleDataCfg } from '.';
@@ -379,7 +380,7 @@ export const expectMatchSnapshot = async (
   await s2.render();
   const data = await asyncGetAllPlainData({
     sheetInstance: s2,
-    split: '\t',
+    split: TAB_SEPARATOR,
     formatOptions,
   });
 

packages/s2-core/src/common/constant/copy.ts

@@ -4,9 +4,11 @@ export enum CopyType {
   ROW,
 }
 
-export const NewLine = '\r\n';
+export const LINE_SEPARATOR = '\r\n';
 
-export const NewTab = '\t';
+export const TAB_SEPARATOR = '\t';
+
+export const CSV_SEPARATOR = ',';
 
 // 每次异步渲染数据的阈值
 export const AsyncRenderThreshold = 5000;

packages/s2-core/src/common/interface/export.ts

@@ -50,7 +50,7 @@ export interface CopyOrExportConfig {
   formatOptions?: FormatOptions;
   separator?: string;
   customTransformer?: (transformer: Transformer) => Partial<Transformer>;
-  isAsyncExport?: boolean;
+  async?: boolean;
 }
 
 export interface CopyAndExportUnifyConfig {
@@ -59,16 +59,37 @@ export interface CopyAndExportUnifyConfig {
   formatData: boolean;
   selectedCells: CellMeta[];
   transformers: Transformer;
-  isAsyncExport: boolean;
+  async: boolean;
 }
 
 export interface CopyAllDataParams {
+  /**
+   * 表格实例
+   */
   sheetInstance: SpreadSheet;
+
+  /**
+   * 数据分割符
+   * @example "\t"
+   */
   split?: string;
+
+  /**
+   * 格式化配置
+   * @example { formatHeader: true, formatData: true }
+   */
   formatOptions?: FormatOptions;
+
+  /**
+   * 导出时支持自定义 (transformer) 数据导出格式化方法
+   * @see https://s2.antv.antgroup.com/manual/advanced/interaction/copy
+   */
   customTransformer?: (transformer: Transformer) => Partial<Transformer>;
-  /** 是否开启异步导出 */
-  isAsyncExport?: boolean;
+
+  /**
+   * 是否开启异步复制/导出
+   */
+  async?: boolean;
 }
 
 export interface SheetCopyConstructorParams {

packages/s2-core/src/utils/export/copy/base-data-cell-copy.ts

@@ -1,4 +1,4 @@
-import { NewTab, type DataItem } from '../../../common';
+import { TAB_SEPARATOR, type DataItem } from '../../../common';
 import type {
   CopyableHTML,
   CopyablePlain,
@@ -51,7 +51,7 @@ export abstract class BaseDataCellCopy {
 
   protected matrixTransformer(
     dataMatrix: string[][],
-    separator = NewTab,
+    separator = TAB_SEPARATOR,
   ): [CopyablePlain, CopyableHTML] {
     return [
       this.matrixPlainTextTransformer(dataMatrix, separator),

packages/s2-core/src/utils/export/copy/common.ts

@@ -1,7 +1,7 @@
 import { escape, map, max } from 'lodash';
 import type { Node } from '../../../facet/layout/node';
 import type { DataItem } from '../../../common';
-import { NewLine, NewTab, ROOT_NODE_ID } from '../../../common';
+import { LINE_SEPARATOR, TAB_SEPARATOR, ROOT_NODE_ID } from '../../../common';
 import {
   type CopyableHTML,
   type CopyablePlain,
@@ -18,11 +18,13 @@ import type { BaseDataSet } from './../../../data-set/base-data-set';
 // 把 string[][] 矩阵转换成 CopyablePlain
 export const matrixPlainTextTransformer = (
   dataMatrix: DataItem[][],
-  separator = NewTab,
+  separator = TAB_SEPARATOR,
 ): CopyablePlain => {
   return {
     type: CopyMIMEType.PLAIN,
-    content: map(dataMatrix, (line) => line.join(separator)).join(NewLine),
+    content: map(dataMatrix, (line) => line.join(separator)).join(
+      LINE_SEPARATOR,
+    ),
   };
 };
 
@@ -183,10 +185,10 @@ export function unifyConfig({
   },
   config: {
     formatOptions = false,
-    separator = NewTab,
+    separator = TAB_SEPARATOR,
     selectedCells = [],
     customTransformer,
-    isAsyncExport = false,
+    async = false,
   },
   isExport,
 }: SheetCopyConstructorParams): CopyAndExportUnifyConfig {
@@ -207,7 +209,7 @@ export function unifyConfig({
     transformers,
     formatData,
     formatHeader,
-    isAsyncExport,
+    async,
   };
 }