logo

S2

  • 使用文档
  • API 文档
  • 图表示例
  • 在线体验
  • 更新日志
  • 所有产品antv logo arrow
  • 2.x
  • 基础配置项
    • S2DataConfig
    • S2Options
      Updated
    • S2Theme
      Updated
    • S2Event
      Updated
  • 基础类
    • SpreadSheet
      Updated
    • Interaction
      Updated
    • Store
    • BaseCell
      Updated
    • BaseDataSet
      Updated
    • Node
    • BaseTooltip
    • BaseFacet
      Updated
    • Hierarchy
      New
    • BaseBBox
      New
    • CellData
      New
  • 分析组件
    • 表组件
      Updated
    • 维度下钻
      Updated
    • 维度切换组件
      Updated
    • 高级排序
      Updated
    • 导出
      Updated
  • 绘图属性
  • 透视组合图拓展 S2Options

导出

上一篇
高级排序
下一篇
绘图属性

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...

React 导出组件 @antv/s2-react-components

import { Export } from '@antv/s2-react-components';
import '@antv/s2-react-components/dist/s2-react-components.min.css'
<Export sheetInstance={s2} />

ExportCfgProps

属性说明类型默认值必选
sheetInstance表格实例SpreadSheet
className类名string
icon展示图标ReactNode
copyOriginalText复制原始数据文案string
copyFormatText复制格式化数据文案string
downloadOriginalText下载原始数据文案string
downloadFormatText下载格式化数据文案string
fileName自定义下载文件名 (csv)stringsheet
async异步复制/导出数据 (默认异步)booleantrue
dropdown下拉菜单配置,透传给 antd 的 Dropdown 组件DropdownProps
customCopyMethod自定义导出组件内部复制处理逻辑(params: CopyAllDataParams) => Promise<string> | string | Promise<Copyable> | Copyable
onCopySuccess复制成功(data: Copyable | string | undefined) => void
onCopyError复制失败(error: unknown) => void
onDownloadSuccess下载成功(data: string) => void
onDownloadError下载失败(error: unknown) => void

复制

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 保持原样