S2

@antv/s2 @antv/s2-react-components

@antv/s2 提供了复制导出的基础能力, @antv/s2-react-components 组件层基于 @antv/s2 和 antd 封装了开箱即用的导出功能。

使用

import React from 'react'
import { SheetComponent } from '@antv/s2-react'
import { Export } from '@antv/s2-react-components'
import '@antv/s2-react/dist/s2-react.min.css';
import '@antv/s2-react-components/dist/s2-react-components.min.css';


const S2Options = {
  interaction: {
    // 开启复制
    copy: {
      enable: true
    }
  }
}

const App = () => {
  const s2Ref = React.useRef()

  return (
    <>
      <Export sheetInstance={s2Ref.current} />
      <SheetComponent
        dataCfg={dataCfg}
        options={S2Options}
        ref={s2Ref}
      />
    </>
  )
}

提示

开启导出功能后，点击右上角的下拉菜单，可以复制和导出（原始/全量）数据。

复制原始数据/复制格式化数据: 可以直接粘贴到 Excel (text/plain), 语雀 (text/html) 等常用应用中。
下载原始数据/下载格式化数据: 生成 csv 文件，可以直接使用 Excel (text/plain) 打开。

查看示例

自定义入口

Export 组件默认入口为 三个点，可以通过 children 的方式自定义。

import { Button } from 'antd'
import { ExportOutlined } from '@ant-design/icons';
import { Export } from '@antv/s2-react-components'
import '@antv/s2-react-components/dist/s2-react-components.min.css';

const App = () => {
  return (
    <Export sheetInstance={s2Ref.current}>
      <Button type="text" icon={<ExportOutlined />}>
        导出数据
      </Button>
    </Export>
  )
}

API

<Export
  onCopySuccess={(data) => {
    console.log('copy success:', data);
  }}
  onDownloadSuccess={(data) => {
    console.log('download success', data);
  }}
/>

查看分析组件 - 导出 API 文档

在趋势分析表中使用

由于趋势分析表数据结构的特殊性，和普通表格的导出有所不同，需要通过 @antv/s2-react-components 提供的 StrategyExport 组件，使用方式和 Export 相同。

import { StrategyExport } from '@antv/s2-react-components'

<StrategyExport sheetInstance={s2Ref.current} />

查看示例

<StrategyExport /> 内部使用的是 strategyCopy 处理数据的复制导出，等价于下面的代码：

import { strategyCopy } from '@antv/s2';
import { Export } from '@antv/s2-react-components'

<Export sheetInstance={s2Ref.current} customCopyMethod={strategyCopy} />

所以，当你有自定义导出组件的诉求时，你也可以通过 strategyCopy 自行封装。

在非 React 应用中使用

提示

本质上，@antv/s2-react-components 的导出组件，只是基于 @antv/s2 提供的能力，封装了相应的 UI, 如果不希望依赖框架，或者希望在 Vue 等框架中使用，都是可以的。

复制

1. 全量复制

注意

S2 会在复制的时候往剪贴板写入两种类型的元数据

text/html
text/plain

粘贴的时候，取决于接收方选择什么类型的数据，对于富文本一般来说接收的是 text/html, 对于 Excel 之类的就是 text/plain, 即带制表符 \t 的纯文本，支持自定义修改。

内置三个 API, 详见下方文档

asyncGetAllData
asyncGetAllPlainData
asyncGetAllHtmlData

const s2DataConfig = {
  fields: {
    rows: ['province', 'city'],
    columns: ['type', 'sub_type'],
    values: ['number'],
  },
  meta: [
    {
      field: 'number',
      name: '数量',
      formatter: (value, record, meta) => {
        return `${value / 100} %`
      }
    },
  ]
}

1.1 在 `@antv/s2` 中使用

import { asyncGetAllData, copyToClipboard } from '@antv/s2'

// 1. 拿到表格数据
const data = await asyncGetAllData({
  sheetInstance: s2,
  split: '\t',
  formatOptions: true,
  // formatOptions: {
  //   formatHeader: true,
  //   formatData: true
  // },

  // 同步复制
  // async: false
});

// 2. 写入到剪切板 （同时包含 `text/html` 和 `text/plain`)
// 同步复制：copyToClipboard(data, false)
copyToClipboard(data)
  .then(() => {
    console.log('复制成功')
  })
  .catch(() => {
    console.log('复制失败')
  })

查看示例

1.2 在 `@antv/s2-react` 中使用

提示

组件层的复制，导出等功能，基于核心层 @antv/s2 透出的一系列工具方法封装，也可以根据实际业务，基于工具方法自行封装。

具体请查看分析组件-导出章节。

1.2.1 原始数据全量复制

对应 @antv/s2 工具方法：

const data = await asyncGetAllData({
  sheetInstance: s2,
  split: '\t',
  formatOptions: {
    formatHeader: false,
    formatData: false
  },
});

1.2.2 格式化数据全量复制

如果配置了 S2DataConfig.meta 对数据有格式化处理, 即 s2DataConfig.meta 中的 name 和 formatter，那么可以开启 withFormat, 这样复制时会拿到格式化之后的数据。

const s2Options = {
  interaction: {
    copy: {
      // 开启复制
      enable: true,
      // 复制时携带表头
      withHeader: true,
      // 复制格式化后的数据
      withFormat: true
    }
  }
}

对应 @antv/s2 工具方法：

const data = await asyncGetAllData({
  sheetInstance: s2,
  split: '\t',
  formatOptions: {
    formatHeader: true,
    formatData: true
  },
});

2. 局部复制

S2 默认提供局部复制的能力，开启后，使用快捷键 Command/Ctrl + C 即可复制选中区域，支持 单选/多选/刷选/区间多选.

const s2Options = {
  interaction: {
    copy: {
      // 是否开启复制
      enable: true,
      // 复制时携带表头
      withHeader: true,
      // 复制格式化后的数据
      withFormat: true,
    },

    // 可选：圈选复制前，需要开启圈选功能
    brushSelection: {
      dataCell: true,
      rowCell: true,
      colCell: true,
    },

    // 可选：多选
    multiSelection: true
  }
};

2.1 复制到 Excel

2.2 复制带 HTML 格式

2.3 复制行头内容

2.4 复制列头内容

2.5 带表头复制

开启 withHeader 后，复制时会携带当前选中数据对应的行列头单元格数据。

const s2Options = {
  interaction: {
    copy: {
      enable: true,
      withHeader: true,
    },
  }
};

3. 自定义数据转换

默认获取 text/plain 和 text/html 两种类型的全量表格数据，可以通过 customTransformer 自定义数据转换。

import { asyncGetAllData } from '@antv/s2'

const data = await asyncGetAllData({
  sheetInstance: s2,
  split: '\t',
  formatOptions: true,
  customTransformer: () => {
    return {
      'text/plain': (data) => {
         return {
           type: 'text/plain',
           content: ``
         };
      },
      'text/html': (data) => {
         return {
           type: 'text/html',
           content: `<td></td>`
         };
      },
    };
  },
})

也可以写在 s2Options 中：

const s2Options = {
  interaction: {
    copy: {
      customTransformer: () => {}
    }
  }
}

查看示例

导出

默认只提供 csv 纯文本格式的导出，如果想导出 xlsx, 保留单元格样式，可以结合 exceljs, sheetjs 等工具自行处理。

1. 导出 CSV

import { asyncGetAllPlainData, download } from '@antv/s2'

// 拿到复制数据 (text/plain)
const data = await asyncGetAllPlainData({
  sheetInstance: s2,
  split: ',',
  formatOptions: true,
  // formatOptions: {
  //   formatHeader: true,
  //   formatData: true
  // },

  // 同步导出
  // async: false
});

// 导出数据 (csv)
download(data, 'filename') // filename.csv

API

asyncGetAllData

获取 text/plain 和 text/html 两种类型的数据，用于复制

[
  {
    "type": "text/plain",
    "content": "省份、t 城市、t 类别、r\n 浙江省、t 杭州市、t 家具、r\n 浙江省、t 绍兴市、t 家具"
  },
  {
    "type": "text/html",
    "content": "<meta charset=\"utf-8\"><table><tbody><tr><td>省份</td><td>城市</td><td>类别</td></tr><tr><td>浙江省</td><td>杭州市</td><td>家具</td></tr><tr><td>浙江省</td><td>绍兴市</td><td>家具</td></tr></tbody></table>"
  }
]

asyncGetAllPlainData

获取 text/plain 类型的数据，用于导出

"省份、t 城市、t 类别、r\n 浙江省、t 杭州市、t 家具、r\n 浙江省、t 绍兴市、t 家具"

asyncGetAllHtmlData

获取 text/html 类型的数据，用于导出

"<meta charset=\"utf-8\"><table><tbody><tr><td>省份</td><td>城市</td><td>类别</td></tr><tr><td>浙江省</td><td>杭州市</td><td>家具</td></tr><tr><td>浙江省</td><td>绍兴市</td><td>家具</td></tr></tbody></table>"

参数	说明	类型	默认值	必选
sheetInstance	s2 实例	SpreadSheet		✓
split	分隔符	`string`		✓
formatOptions	是否使用 S2DataConfig.Meta 进行格式化，可以分别对数据单元格和行列头进行格式化，传 `boolean` 会同时对单元格和行列头生效。	`boolean \| { formatHeader?: boolean, formatData?: boolean }`	`true`
customTransformer	导出时支持自定义 (transformer) 数据导出格式化方法	(transformer: `Transformer`) => `Partial<Transformer>`
async	是否异步复制/导出（当浏览器不支持 `requestIdleCallback` 时，会强制降级为同步)	boolean	`true`

copyToClipboard

参数	说明	类型	默认值	必选
data	数据源	`string`		✓
async	是否异步复制数据（默认异步）	`boolean`	`true`

download

参数	说明	类型	默认值	必选
data	数据源	`string`		✓
filename	文件名称	`string`		✓

CopyMIMEType

enum CopyMIMEType {
  PLAIN = 'text/plain',
  HTML = 'text/html',
}

FormatOptions

type FormatOptions =
  | boolean
  | {
      formatHeader?: boolean;
      formatData?: boolean;
    };

CopyAllDataParams

interface CopyAllDataParams {
  sheetInstance: SpreadSheet;
  split?: string;
  formatOptions?: FormatOptions;
  customTransformer?: (transformer: Transformer) => Partial<Transformer>;
  async?: boolean;
}

Transformer

type CopyablePlain = {
  type: CopyMIMEType.PLAIN;
  content: string;
};

type CopyableHTML = {
  type: CopyMIMEType.HTML;
  content: string;
};

type MatrixPlainTransformer = (
  data: DataItem[][],
  separator?: string,
) => CopyablePlain;

type MatrixHTMLTransformer = (data: DataItem[][]) => CopyableHTML;

interface Transformer {
  [CopyMIMEType.PLAIN]: MatrixPlainTransformer;
  [CopyMIMEType.HTML]: MatrixHTMLTransformer;
}

参数	说明	类型	默认值	必选
type	复制内容的 MIMEType	`CopyMIMEType`		✓
transformer	处理函数	`MatrixHTMLTransformer \| MatrixPlainTransformer`		✓

特殊字符处理规则说明

根据 CSV规范及 Excel的处理规则，S2会按以下规则处理特殊字符：

字段包裹规则
当字段包含以下任意字符时，会用双引号包裹整个字段：
, " \r \n \t
双引号转义规则
字段中的双引号 " 会转义为两个双引号 ""：
换行符处理规则
为兼容直接粘贴到 Excel 单元格的场景：
- 将独立的 \n 替换为 \r\n
- 已有的 \r\n 保持原样

导出

使用

提示

自定义入口

API

在趋势分析表中使用

在非 React 应用中使用

提示

复制

1. 全量复制

注意

1.1 在 @antv/s2 中使用

1.2 在 @antv/s2-react 中使用

提示

1.2.1 原始数据全量复制

1.2.2 格式化数据全量复制

2. 局部复制

2.1 复制到 Excel

2.2 复制带 HTML 格式

2.3 复制行头内容

2.4 复制列头内容

2.5 带表头复制

3. 自定义数据转换

导出

1. 导出 CSV

API

asyncGetAllData

asyncGetAllPlainData

asyncGetAllHtmlData

copyToClipboard

download

CopyMIMEType

FormatOptions

CopyAllDataParams

Transformer

特殊字符处理规则说明

1.1 在 `@antv/s2` 中使用

1.2 在 `@antv/s2-react` 中使用