logo

S2

  • 使用文档
  • API 文档
  • 图表示例
  • 在线体验
  • 更新日志
  • 所有产品antv logo arrow
  • 2.x
  • 简介
  • 快速上手
  • 基础教程
    • 基本概念
      Updated
    • 表形态
      • 透视表
        Updated
      • 明细表
        Updated
    • 字段标记
      Updated
    • 小计总计
    • 排序
      • 基础排序
        Updated
      • 组内排序
        Updated
    • 主题配置
      Updated
    • Tooltip
      Updated
    • 数据格式化
      New
    • 多行文本
      New
    • 国际化
    • 分页
      New
  • 进阶教程
    • 单元格渲染类型
      • 链接
      • 图片
        New
      • 视频
        New
      • 迷你图表
      • 结合@antv/g2
      • 自定义渲染
    • 自定义
      • 自定义 Hook
        Updated
      • 自定义行列头分组
        New
      • 自定义 Icon
        Updated
      • 自定义单元格对齐方式
        Updated
      • 自定义单元格宽高
        Updated
      • 自定义排序操作
        Updated
      • 自定义折叠/展开节点
        New
    • 交互
      • 基础交互
        Updated
      • 自定义交互
      • 隐藏列头
        Updated
      • 行列宽高调整
        Updated
      • 合并单元格
      • 滚动
        Updated
      • 复制与导出
        New
      • 高亮/选中单元格
        New
    • 分析组件
      • 简介
        New
      • 高级排序
        Updated
      • 维度切换
        Updated
      • 导出
        Updated
      • 分页
        Updated
      • 维度下钻
        Updated
    • 表格组件
      • 编辑表
      • 趋势分析表
        Updated
    • 高清适配
      Updated
    • 获取表格实例
    • 表格自适应
    • 获取单元格数据
      Updated
    • 注册 AntV/G 插件
      New
    • 透视组合图
      Experimental
    • Vue 3.0 组件 (停止维护)
  • 扩展阅读
    • 数据流处理
      • 透视表
      • 明细表
    • 布局流程
      • 透视表
      • 明细表
    • 性能介绍
      Updated
  • 贡献指南
  • 常见问题
  • S2 2.0 升级指南

导出

上一篇
维度切换
下一篇
分页

Resources

Ant Design
Galacea Effects
Umi-React 应用开发框架
Dumi-组件/文档研发工具
ahooks-React Hooks 库

社区

体验科技专栏
seeconfSEE Conf-蚂蚁体验科技大会

帮助

GitHub
StackOverflow

more products更多产品

Ant DesignAnt Design-企业级 UI 设计语言
yuque语雀-知识创作与分享工具
EggEgg-企业级 Node 开发框架
kitchenKitchen-Sketch 工具集
GalaceanGalacean-互动图形解决方案
xtech蚂蚁体验科技
© Copyright 2025 Ant Group Co., Ltd..备案号:京ICP备15032932号-38

Loading...

@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}
/>
</>
)
}

提示

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

  1. 复制原始数据/复制格式化数据: 可以直接粘贴到 Excel (text/plain), 语雀 (text/html) 等常用应用中。
  2. 下载原始数据/下载格式化数据: 生成 csv 文件,可以直接使用 Excel (text/plain) 打开。
Your browser does not support HTML video.
查看示例

自定义入口

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 原始数据全量复制
originFullCopy

对应 @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
}
}
}
formatFullCopy

对应 @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

excelCopy

2.2 复制带 HTML 格式

HTMLCopy

2.3 复制行头内容

CopyCol

2.4 复制列头内容

CopyRow

2.5 带表头复制

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

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

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>"
参数说明类型默认值必选
sheetInstances2 实例SpreadSheet✓
split分隔符string✓
formatOptions是否使用 S2DataConfig.Meta 进行格式化,可以分别对数据单元格和行列头进行格式化,传 boolean 会同时对单元格和行列头生效。boolean | { formatHeader?: boolean, formatData?: boolean }true
customTransformer导出时支持自定义 (transformer) 数据导出格式化方法(transformer: Transformer) => Partial<Transformer>
async是否异步复制/导出(当浏览器不支持 requestIdleCallback 时,会强制降级为同步)booleantrue
copyToClipboard
参数说明类型默认值必选
data数据源string✓
async是否异步复制数据(默认异步)booleantrue
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复制内容的 MIMETypeCopyMIMEType✓
transformer处理函数MatrixHTMLTransformer | MatrixPlainTransformer✓

特殊字符处理规则说明

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

  1. 字段包裹规则
    当字段包含以下任意字符时,会用双引号包裹整个字段:
    , " \r \n \t

  2. 双引号转义规则

    字段中的双引号 " 会转义为两个双引号 "":

  3. 换行符处理规则
    为兼容直接粘贴到 Excel 单元格的场景:

    • 将独立的 \n 替换为 \r\n
    • 已有的 \r\n 保持原样