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 升级指南

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

本文档将帮助你从 S2 1.x 版本升级到 S2 2.x 版本。

🏠 官网地址变化

注意

原官网 https://s2.antv.vision 和 https://antv-s2.gitee.io 不再维护和使用,请访问最新的网址,以确保您看到的不是过时的文档。

  • 原 v1 官网迁移至 https://s2-v1.antv.antgroup.com.
  • 原 https://s2.antv.antgroup.com 将作为 v2 默认官网。

🏷️ npm dist-tag 变化

什么是 dist-tag ?

S2 2.0 正式版已发布,现在 npm 的 latest dist-tag 默认对应 2.x 版本,即:

  • @antv/s2@latest => @antv/[email protected]

  • @antv/s2@latest => @antv/[email protected]

注意

如通过此类未指定具体版本的方式安装,请注意不要意外安装到 2.0 新版本。

⏰ 已停止维护的包和版本

  • 1.x 版本现已停止维护,不再继续更新,不再修复 bug,不再支持新特性。
  • @antv/s2-vue 现已停止维护,由于精力投入有限,出于维护成本,包下载量等因素综合考虑,从 2.0.0 正式版后不再继续更新,请基于 @antv/s2 自行封装,或 fork 仓库进行二次开发社区版本。

请根据 升级指南 尽快升级到 2.x 版本。

🛺 从 2.0.0-next.x 到 2.0.0 正式版

如果你使用的是内测版本 2.0.0-next.x, 升级到 2.0 正式版时额外需要注意以下几点不兼容改动:

  • 构建产物调整
  • 移除 Ant Design 组件库依赖
  • Tooltip 操作项默认菜单组件移除

📦 安装

使用基础版本 @antv/s2

使用 npm 或 yarn 或 pnpm 安装

# npm
$ npm install @antv/s2 --save
# yarn
$ yarn add @antv/s2
# pnpm
$ pnpm add @antv/s2

使用 React 版本 @antv/s2-react

npm install @antv/s2 @antv/s2-react --save

使用 React 版本分析组件 @antv/s2-react-components

npm install @antv/s2 @antv/s2-react-components antd @ant-design/icons --save

使用 Vue3 版本 @antv/s2-vue 停止维护

注意

@antv/s2-vue 现已停止维护,由于精力投入有限,出于维护成本,包下载量等因素综合考虑,从 2.0.0 正式版后不再继续更新,请基于 @antv/s2 自行封装,或 fork 仓库进行二次开发社区版本。

npm install @antv/s2 @antv/s2-vue [email protected] --save

提示

创建 S2 表格有三种方式,基础类版本 @antv/s2 和 基于 @antv/s2 封装的 React 和 Vue3 版本:

  1. 基础版本 @antv/s2: 基于 Canvas 和 AntV/G 6.0 开发,提供基本的表格展示/交互等能力。

版本依赖:无

  1. React 版本 @antv/s2-react: 基于 React 18, 和 @antv/s2 封装,兼容 React 16/17 版本,同时提供配套的 分析组件 (@antv/s2-react-components).

版本依赖:

"peerDependencies": {
"@antv/s2": "^2.0.0",
"react": ">=16.9.0",
"react-dom": ">=16.9.0"
}
  1. Vue 版本 @antv/s2-vue: 基于 Vue3, @antv/s2 , [email protected] 封装。停止维护

版本依赖:

"peerDependencies": {
"@antv/s2": "^2.0.0",
"ant-design-vue": "^3.2.0",
"vue": ">=3.x"
}

也就是说 @antv/s2 和框架无关,无任何额外依赖, 你可以在 Vue, Angular 等任意框架中使用。

包名稳定版包大小下载量
@antv/s2latestsizedownload
@antv/s2-reactlatestsizedownload
@antv/s2-react-componentslatestsizedownload
@antv/s2-vue(停止维护)latestsizedownload

如何获取新版本发布通知?

  • 订阅:https://github.com/antvis/S2/releases.atom 来获得新版本发布的通知。
  • Watch S2 代码仓库, 选择 Custom - Releases 来获取消息推送。

preview

⭐ 新增功能

官网目录标记为 New 和 Updated 则表示新增功能,也可以查看官方语雀博客 S2 2.0 表格看数新纪元.

📦 构建产物调整

  • ESModule/CommonJS

所有包的 ESModule (esm) 和 CommonJS (lib) 构建产物从 Bundle 调整为 Bundless, 其所依赖的子模块会被直接拷贝输出,不再做编译,以便于更好的支持代码 tree shaking, 减少包体积。

  • UMD

所有包的 UMD (dist) 构建产物依然为 Bundle 单文件,文件名和全局变量名有所调整:

包名文件名(修改前)文件名(修改后)
@antv/s2dist/index.min.js dist/style.min.cssdist/s2.min.css dist/s2.min.css
@antv/s2-reactdist/index.min.js dist/style.min.cssdist/s2-react.min.css dist/s2-react.min.css
@antv/s2-vuedist/index.min.js dist/style.min.cssdist/s2-vue.min.css dist/s2-vue.min.css
包名全局变量名(修改前)全局变量名(修改后)
@antv/s2S2S2
@antv/s2-reactS2-ReactS2React
@antv/s2-vueS2-VueS2Vue

📣 不兼容的变化

基础包 (s2) @antv/s2

底层渲染引擎升级为 AntV/G 6.0

表格绘制引擎升级到 G 6.0 大版本,和 AntV 其他技术栈 保持同步,渲染方式升级为异步。

- s2.render()
+ await s2.render()

如果在你的业务场景中,有使用 G 的一些自定义 shape, 如自定义矩形,图片等场景,或者其他能力,请注意替换,具体请查看 G 的 官网文档.

+ import { Image } from '@antv/g';
+ this.appendChild(new Image({ style: {} }))
- this.addShape('image', { attrs: {} });

其他 图形 同理,不再过多赘述。

S2 和 G 的配置分离

在 1.x 中,我们会将 S2Options 中的 supportsCSSTransform 和 devicePixelRatio 等属性透传给 G.

在 2.x 中:

  • 移除 devicePixelRatio 和 supportsCSSTransform (supportCSSTransform).
  • 新增 transformCanvasConfig 支持透传 G 的配置,以及注册插件,具体请查阅 注册 AntV/G 插件 相关文档。
const s2Options = {
transformCanvasConfig(renderer) {
renderer.setConfig({ enableDirtyCheck: true })
renderer.registerPlugin(new PluginA11y({ enableExtractingText: true }));
return {
supportsCSSTransform: true,
devicePixelRatio: 2
};
},
}

自定义宽高配置调整

  1. rowCfg/colCfg/cellCfg 调整为 rowCell/colCell/dataCell.
const s2Options = {
style: {
- rowCfg: {},
- colCfg: {},
- cellCfg: {},
+ rowCell: {},
+ colCell: {},
+ dataCell: {},
}
}
  1. 废弃 widthByFieldValue, 新增 widthByField.
  2. 行列宽高支持动态配置。
export interface BaseCellStyle {
width?: number | (node) => number;
- height?: number;
+ height?: number | (node) => number;
- widthByFieldValue?: Record<string, number>;
+ widthByField?: Record<string, number>;
heightByField?: Record<string, number>;
}
  1. 现在 widthByField 和 heightByField 同时支持维度 id 和 维度 field.

具体请查看 自定义单元格宽高 相关文档。

Tooltip 配置调整

  1. row/col/data/corner 调整为 rowCell/colCell/dataCell/cornerCell.
const s2Options = {
tooltip: {
- row: {},
- col: {},
- data: {},
- corner: {},
+ rowCell: {},
+ colCell: {},
+ dataCell: {},
+ cornerCell: {},
}
}
  1. showTooltip 和 renderTooltip 调整为 enable 和 render.
const s2Options = {
tooltip: {
- showTooltip: true,
- renderTooltip: () => new CustomTooltip(),
+ enable: true,
+ render: () => new CustomTooltip(),
}
}
  1. API 方式调用的配置变更

enterable 属性移除,showSingleTips 变更为 onlyShowCellText, onlyMenu 变更为 onlyShowOperator

s2.showTooltip({
options: {
- enterable: true,
- showSingleTips: true,
+ onlyShowCellText: true,
- onlyMenu: true,
+ onlyShowOperator: true
},
});

具体请查看 Tooltip 相关文档。

复制导出调整

  1. 配置收拢到 interaction.copy 下,新增 customTransformer 自定义转换器。
const s2Options = {
interaction: {
- enableCopy: true,
- copyWithHeader: true,
- copyWithFormat: true
+ copy: {
+ enable: true,
+ withHeader: true,
+ withFormat: true,
+ customTransformer: () => {}
+ },
}
}
  1. 废弃 copyData, 新增 asyncGetAllData, asyncGetAllPlainData, asyncGetAllHtmlData 等 API, 支持异步获取数据。
- const data = copyData(spreadsheet, '\t', false)
+ const data = await asyncGetAllData({
+ sheetInstance: s2,
+ split: '\t',
+ formatOptions: false,
+ async: true,
});
  1. copyToClipboard 第二个参数含义 从 sync 变更为 async.
- const data = copyToClipboard(data: string, sync: boolean)
+ const data = copyToClipboard(data: Copyable | string, async: boolean)
  1. 复制默认开启。
  2. 复制导出默认异步。

具体请查看 复制与导出 相关文档。

刷选配置调整

  1. row/col/data 调整为 rowCell/colCell/dataCell。
const s2Options = {
interaction: {
- brushSelection: {
- row: false,
- col: false,
- data: true,
- },
+ brushSelection: {
+ rowCell: true,
+ colCell: true,
+ dataCell: true,
+ }
}
}
  1. 所有单元格默认开启刷选。

具体请查看 基础交互 相关文档。

headerActionIcons 配置调整

iconsNames 调整为 icons, 废弃 action, 新增 onClick 和 onHover.

const s2Options = {
headerActionIcons: [
{
- iconNames: ['SortDown'],
- action: () => {}
+ icons: ['SortDown'],
+ onClick: () => {}
+ onHover: () => {}
},
],
}

现在支持配置 position (icon 相对文本的位置) 和 fill (颜色配置), 并且支持给单个 icon 配置独立的 displayCondition 和 defaultHide.

const s2Options = {
headerActionIcons: [
{
+ icons: [{
+ name: 'SortDown',
+ position: 'right',
+ fill: '#000',
+ displayCondition: () => {},
+ defaultHide: () => {},
+ }]
},
],
}

具体请查看 自定义 Icon 相关文档。

customSVGIcons 配置调整

svg 调整为 src, 保持 API 统一。

const s2Options = {
customSVGIcons: [
{
name: 'CustomIcon',
- svg: 'https://gw.alipayobjects.com/zos/bmw-prod/f44eb1f5-7cea-45df-875e-76e825a6e0ab.svg',
+ src: 'https://gw.alipayobjects.com/zos/bmw-prod/f44eb1f5-7cea-45df-875e-76e825a6e0ab.svg',
},
]
}

树状结构配置和回调事件调整

  1. 行头折叠展开配置调整

废弃 rowExpandDepth/collapsedRows/hierarchyCollapse, 使用更表意的 expandDepth/collapseFields/collapseAll 代替。

const s2Options = {
hierarchyType: 'tree',
style: {
- rowExpandDepth: 0,
- collapsedRows: {},
- hierarchyCollapse: true,
+ rowCell: {
+ expandDepth: 0,
+ collapseFields: {},
+ collapseAll: true
}
},
}
  1. 树状结构下行头宽度配置调整

原 treeRowsWidth 重命名为 rowCell.treeWidth。

const s2Options = {
hierarchyType: 'tree',
style: {
- treeRowsWidth: 200
+ rowCell: {
+ treeWidth: 200,
+ }
},
}
  1. customTree 和 customTreeItems 已废弃。

原本自定义树状结构的方式已废弃,现在自定义结构同时支持 平铺 和 树状 两种模式。

const s2Options = {
- hierarchyType: 'customTree',
+ hierarchyType: 'tree',
}
const s2DataConfig = {
fields: {
- customTreeItems: [
- {
- key: 'custom-node-1',
- title: '自定义节点 A',
- description: '自定义节点 A 描述',
- children: []
- }
+ rows: [
+ {
+ field: 'custom-node-1',
+ title: '自定义节点 A',
+ description: '自定义节点 A 描述',
+ children: []
+ }
]
}
}

具体请查看 自定义行列头分组 相关文档。

  1. 行头单元格折叠展开事件划分到 RowCell

移除 LAYOUT_AFTER_COLLAPSE_ROWS

- S2Event.LAYOUT_TREE_ROWS_COLLAPSE_ALL
+ S2Event.ROW_CELL_ALL_COLLAPSED
- S2Event.LAYOUT_COLLAPSE_ROWS
- S2Event.LAYOUT_AFTER_COLLAPSE_ROWS
+ S2Event.ROW_CELL_COLLAPSED

树状结构 icon 折叠展开状态同步

现在行头节点的 icon 展开/收起,会同步更新角头 icon(全部展开/收起)的状态。

行列冻结配置

透视表和明细表的行列冻结配置统一收拢到 frozen。

在透视表中,frozenFirstRow 使用 rowCount: 1 替代。在明细表多级列头冻结时,在 1.x 中是以最最顶层节点为准,而在 2.x 是以叶子节点的数量为准。

const s2Options = {
- frozenRowHeader: true,
- frozenFirstRow: true,
- frozenRowCount: 1;
- frozenColCount: 1;
- frozenTrailingRowCount: 1;
- frozenTrailingColCount: 1;
+ frozen: {
+ rowHeader: true,
+ rowCount: 1;
+ colCount: 1;
+ trailingRowCount: 1;
+ trailingColCount: 1;
+ }
}

透视表冻结行头配置变更

rowHeader 现在支持传递 number , 如果为数值则表示开启冻结行头,并自定义行头最大冻结宽度 (0 - 1)。

const s2Options = {
frozen: {
- rowHeader: true,
+ rowHeader: true,
+ rowHeader: 0.5,
}
}

高清适配配置调整

const s2Options = {
- hdAdapter: true,
+ hd: true,
}

字段标记

文本字段标记能力和 文本主题配置 保持一致,支持字体大小,透明度,对齐方式等配置。

const s2Options = {
conditions: {
text: [
{
field: 'city',
mapping() {
return {
fill: '#DB6BCF',
+ fontSize: 16,
+ opacity: 0.8,
+ textAlign: 'right',
};
},
},
]
},
}

具体请查看 字段标记 相关文档和 文本标记示例。

序号配置变更

序号相关配置统一收拢在 seriesNumber.

const s2Options = {
- showSeriesNumber: true,
- seriesNumberText: '序号'
+ seriesNumber: {
+ enable: true,
+ text: '序号'
+ }
}

单元格宽高拖拽逻辑变更

  1. 在 1.x 中,宽高调整对所有单元格生效,2.x 新增 rowResizeType/colResizeType 选择对 当前 (current), 选中 (selected), 还是 所有 (all) 单元格生效。
const s2Options = {
interaction: {
resize: {
+ rowResizeType: 'current', // 'all' | 'selected'
+ colResizeType: 'current' // 'all' | 'selected'
}
}
}
  1. 默认调整只对当前单元格生效。
  2. 宽高调整后现在不再重置选中状态,仅关闭 tooltip 提示。
  3. 现在支持多选后,进行批量调整。

具体请查看 行列宽高调整 相关文档。

Facet 变更

  1. 静态属性 layoutResult 废弃,使用 s2.facet.getLayoutResult() 动态获取,现在包含 角头节点 (cornerNodes) 和 序号节点 (seriesNumberNodes)。
- s2.facet.layoutResult
+ s2.facet.getLayoutResult()
  1. getCellMeta 从 layoutResult 中移除,移动到 facet 层级,现在 layoutResult 只包含布局节点。
- s2.facet.layoutResult.getCellMeta(rowIndex, colIndex)
+ s2.facet.getCellMeta(rowIndex, colIndex)
  1. 布局结构 layoutResult 新增 角头节点 (cornerNodes) 和 序号节点 (seriesNumberNodes).
export interface LayoutResult {
colNodes: Node[];
colLeafNodes: Node[];
colsHierarchy: Hierarchy;
rowNodes: Node[];
rowsHierarchy: Hierarchy;
rowLeafNodes: Node[];
- getCellMeta: (rowIndex: number, colIndex: number) => ViewMeta
+ seriesNumberNodes?: Node[];
+ cornerNodes?: Node[];
}
  1. 透视表和明细表的数值单元格元数据格式统一,现在 cellMeta 中都包含 query/rowQuery/colQuery.

透视表:

{
rowQuery: {
"province": "浙江省",
"city": "宁波市"
},
colQuery: {
"sub_type": "沙发",
"type": "家具",
"$$extra$$": "number"
},
+ query: {
+ "province": "浙江省",
+ "city": "宁波市",
+ "sub_type": "沙发",
+ "type": "家具",
+ "$$extra$$": "number"
+ }
}

明细表:

{
+ rowQuery: {
+ "rowIndex": 1,
+ },
+ colQuery: {
+ "colIndex": 2,
+ },
+ query: {
+ "rowIndex": 1,
+ "colIndex": 2
+ }
}
  1. 原 s2.getContentHeight() 废弃,移动到 s2.facet.getContentHeight() 中。
- s2.getContentHeight()
+ s2.facet.getContentHeight()
+ s2.facet.getContentWidth()
  1. 获取布局节点相关 API,移动至 s2.facet 命名空间下。并新增丰富的 语法糖.
- s2.getRowNodes()
- s2.getRowLeafNodes()
- s2.getColumnLeafNodes()
- s2.getColumnNodes()
- s2.interaction.getPanelGroupAllDataCells()
- s2.interaction.getPanelGroupAllUnSelectedDataCells()
+ s2.facet.getRowNodes()
+ s2.facet.getRowLeafNodes()
+ s2.facet.getColLeafNodes()
+ s2.facet.getColNodes()
+ s2.facet.getDataCells()
+ s2.interaction.getUnSelectedDataCells() // 和交互相关,所以重命名后还是保留在 interaction 命名空间下

具体请查看 获取单元格数据 和 BaseFacet 相关文档。

渲染参数变更

render 函数的参数从 boolean 扩展为 boolean | object, 当为 boolean 时,等价与 { reloadData: boolean }

- s2.render(true)
- s2.render(false)
- s2.render(false, { reBuildHiddenColumnsDetail: false })
+ s2.render({ reloadData: true }) // 等价于 s2.render(true)
+ s2.render({ reloadData: false }) // 等价于 s2.render(false)
+ s2.render({
+ reloadData: false,
+ rebuildHiddenColumnsDetail: false,
+ });

reBuildDataSet 重命名为 rebuildDataSet: reBuildHiddenColumnsDetail 重命名为 rebuildHiddenColumnsDetail:

s2.render({
- reBuildDataSet: false,
+ rebuildDataSet: false,
- reBuildHiddenColumnsDetail: false,
+ rebuildHiddenColumnsDetail: false,
});

小计总计配置参数变更

总计配置统一增加 grandTotals 和 subTotals 前缀,避免歧义。

const s2Options = {
totals: {
row: {
- calcTotals: {}.
- reverseLayout: true,
- label: '总计'
- subLabel: '小计'
- totalsGroupDimensions: [],
- reverseSubLayout: true,
+ calcGrandTotals: {}.
+ reverseGrandTotalsLayout: true,
+ grandTotalsLabel: '总计',
+ subTotalsLabel: '小计',
+ grandTotalsGroupDimensions: [],
+ reverseSubTotalsLayout: true
};
}
}

绘制自定义文本 API 变更

绘制多列文本 drawObjectText 函数更名为 drawCustomContent.

- import { drawObjectText } from '@antv/s2'
+ import { drawCustomContent } from '@antv/s2'

数据集处理逻辑变更

对于多个 values 的数据,现在期望一个数据项中就包含所有的 values 信息。

{
fields: {
rows: ["province", "city"],
columns: ["type", "subType"],
values: ["number1", "number2"],
}
}
- [
- {
- province: '辽宁省',
- city: '达州市',
- type: '桌子',
- subType: '家具',
- number1: 3482.28,
- },
- {
- province: '辽宁省',
- city: '达州市',
- type: '桌子',
- subType: '家具',
- number2: 34,
- },
- ];
+ [
+ {
+ province: '辽宁省',
+ city: '达州市',
+ type: '桌子',
+ subType: '家具',
+ number1: 3482.28,
+ number2: 34,
+ },
+ ];

数据集查询逻辑变更

  1. 查询字段从 string 变更为 CustomTreeNode | string.
- s2.dataSet.getField(field: string)
- s2.dataSet.getFieldMeta(field: string)
- s2.dataSet.getFieldName(field: string)
- s2.dataSet.getFieldFormatter(field: string)
+ s2.dataSet.getField(field: CustomTreeNode | string)
+ s2.dataSet.getFieldMeta(field: CustomTreeNode | string)
+ s2.dataSet.getFieldName(field: CustomTreeNode | string)
+ s2.dataSet.getFieldFormatter(field: CustomTreeNode | string)
  1. 获取单元格数据 API 的参数统一。
- s2.dataSet.getCellData(params: CellDataParams)
+ s2.dataSet.getCellData(params: GetCellDataParams)
- s2.dataSet.getMultiData(query: DateType, params: MultiDataParams)
- s2.dataSet.getMultiData(query: DataType, isTotals?: boolean, isRow?: boolean, drillDownFields?: string[], includeTotalData:boolean)
+ s2.dataSet.getCellMultiData(params: GetCellMultiDataParams)

具体请查看 获取单元格数据 相关文档。

S2DataConfig.totalData 配置移除

totalData 和 data 合并,不再需要 totalData 配置。

{
- data: [...],
- totalData: [...],
+ data: [...data, ...totalData],
}

透视表数值单元格元数据数据结构变更

this.meta.data 数据结构变更:

{
- "number": 7789,
- "province": "浙江省",
- "city": "杭州市",
- "type": "家具",
- "sub_type": "桌子",
+ "extraField": "number",
+ "raw": {
+ "number": 7789,
+ "province": "浙江省",
+ "city": "杭州市",
+ "type": "家具",
+ "sub_type": "桌子"
+ },
+ "$$extra$$": "number",
+ "$$value$$": 7789,
+ "$$origin$$": {
+ "number": 7789,
+ "province": "浙江省",
+ "city": "杭州市",
+ "type": "家具",
+ "sub_type": "桌子"
+ }
}

具体请查看 CellData 相关文档。

单元格刷选选中状态变更

1.x 中,行列头刷选选中状态为 brushSelected, 数值单元格的刷选选中状态为 selected, 2.x 中做了进一步统一和区分:

s2.interaction.getState()
// 行头
- stateName: "brushSelected"
+ stateName: "rowCellBrushSelected"
// 列头
- stateName: "brushSelected"
+ stateName: "colCellBrushSelected"
// 数值
- stateName: "selected"
+ stateName: "dataCellBrushSelected"

全选 API 逻辑调整

在 1.x, 全选本质上是高亮,只有样式更新,并不是真的选中,在 2.x 中切换为正确的语义,并且能获取到选中的单元格。

s2.interaction.selectAll()
- s2.interaction.getActiveCells() // []
+ s2.interaction.getActiveCells() // [CellA, CellB]

选中单元格 API 调整

selectHeaderCell 变更为 changeCell, 支持所有类型单元格的选中。同时支持 选中 (selectCell) 和 高亮 (highlightCell) 等语法糖。

- s2.interaction.selectHeaderCell(selectHeaderCellInfo: SelectHeaderCellInfo)
+ s2.interaction.changeCell(options: ChangeCellOptions)
+ s2.interaction.selectCell(cell: S2CellType)
+ s2.interaction.highlightCell(cell: S2CellType)

同时支持 animate(是否展示滚动动画) 和 skipScrollEvent (是否触发滚动事件) 配置。

s2.interaction.selectCell(cell, {
animate: true,
skipScrollEvent: true
})

具体请查看 高亮/选中单元格 相关文档。

滚动 API 调整

滚动 API s2.updateScrollOffset 移除,统一至 s2.interaction 命名空间下。同时支持 scrollToCell 和 scrollToTop 等语法糖。

- s2.updateScrollOffset(offsetConfig: ScrollOffsetConfig)
+ s2.interaction.scrollTo(offsetConfig: ScrollOffsetConfig)

同时支持 skipScrollEvent(是否触发滚动事件) 配置。

s2.interaction.scrollTo({
+ skipScrollEvent: false
})

具体请查看 滚动 相关文档。

配置预处理 API 变更
- import { getSafetyOptions, getSafetyDataConfig } from '@antv/s2'
+ import { setupOptions, setupDataConfig } from '@antv/s2'

空数据占位符配置变更

除了支持配置单元格的空数据占位符,现在支持配置明细表的 空数据状态,类似于 Ant Design 的 Empty 组件 的空状态效果,配置独立为 cell 和 empty 两个配置项,以区分两种状态。

const s2Options = {
- placeholder: "-",
+ placeholder: {
+ cell: '-'
+ }
}
const s2Options = {
+ placeholder: {
+ empty: {
+ icon: 'Empty',
+ description: '暂无数据'
+ }
+ }
}

具体请查看 自定义空数据占位符 和 自定义单元格空数据占位符 示例。

内部常量重命名

- import { ROOT_ID, ID_SEPARATOR } from '@antv/s2'
+ import { ROOT_NODE_ID, NODE_ID_SEPARATOR } from '@antv/s2'

如有消费请注意修改,具体请查看 源代码定义.

自定义数值单元格参数变更

增加第二个参数 spreadsheet, 和其他单元格保持一致。

const s2Options = {
width: 600,
- dataCell: (viewMeta) => {
- return new CustomDataCell(viewMeta, viewMeta.spreadsheet);
- }
+ dataCell: (viewMeta, spreadsheet) => {
+ return new CustomDataCell(viewMeta, spreadsheet);
+ }
}

链接跳转逻辑和参数变更

  1. 现在链接跳转支持对 列头 标记,且明细表同时对 列头 和 数值 生效(可自定义规则)。
  2. 回调参数 key 调整为 field, cellData 调整为 meta.
s2.on(S2Event.GLOBAL_LINK_FIELD_JUMP, (data) => {
- const { key, cellData, record } = data;
+ const { field, meta, record } = data;
});

具体请查看 链接跳转 相关文档。

行列维值为空时 ID 生成规则变更

在 1.x 中由于会将维值转为字符串,如果维值为空 (null), 会转换成 "null", 导致无法获取原始维值,2.x 版本中会对该情况增加特殊标识,便于识别 null 的情况,正确识别原始维值,以及空值占位符逻辑。

{
- id: 'root[&]null',
- value: 'null'
+ id: 'root[&]$$null$$',
+ value: null
}

数值单元格获取数值范围区间方式变更

- dataCell.valueRangeByField
+ dataCell.getValueRange()

分割线主题配置默认值变更

分割线的 颜色 和 透明度 在没有默认值的情况下,默认和所在区域对应的单元格边框保持一致。

splitLine: {
- horizontalBorderColor: basicColors[12],
- horizontalBorderColorOpacity: 0.2,
- verticalBorderColor: basicColors[12],
- verticalBorderColorOpacity: 0.25,
}

单元格默认 padding 变更

paddingTop 和 paddingBottom 调整为 8px.

{
- top: 4,
+ top: 8,
- bottom: 4,
+ bottom: 8
}

自定义 hook 变更

  1. 原 layoutDataPosition 废弃,新增 layoutCellMeta 用于自定义单元格元数据。
const s2Options = {
- layoutDataPosition: (s2, getCellData) => {}
+ layoutCellMeta: (cellMeta) => {}
}

具体请查看 自定义单元格元数据 相关示例。

组件层 (s2-react) @antv/s2-react

移除 Ant Design 组件库依赖

INFO

2.0 正式版本中移除了 antd 的依赖,组件内部更轻量,不再受项目 antd 的版本限制,升级更平滑,推荐自行组合使用。

表头组件移除

header 属性移除,相关配置 (switcher, export, advancedSort) 等对应的组件迁移至 @antv/s2-react-components 中,可以单独按需引入。

<SheetComponent
- header={{
- title: "",
- description: "",
- switcher: { open: true },
- export: { open: true },
- advancedSort: { open: true },
- }}
/>
组件内部的 ConfigProvider 移除

SheetComponent 不再包裹 antd 的 <ConfigProvider /> 全局配置组件,可以自行在外层嵌套 <ConfigProvider /> 组件,避免不同 antd 版本的兼容性问题。

import { ConfigProvider } from 'antd'
<SheetComponent>
- <ConfigProvider />
</SheetComponent>
+ <ConfigProvider>
+ <SheetComponent />
+ </ConfigProvider>
组件内部的 Spin 组件移除
import { Spin } from 'antd'
<SheetComponent>
- <Spin />
</SheetComponent>
+ <Spin>
+ <SheetComponent />
+ </Spin>

1.x 的 <SheetComponent /> 内部会包裹 antd 的 <Spin /> 组件。现已移除,不再有 loading 效果,新增 onLoading, 可以自行在外层嵌套相关组件,组合使用。

通常来说,onLoading 的效果感知不强,推荐根据业务侧 API 请求状态,控制 loading 效果。

import { Spin } from 'antd'
function App() {
const [loading, setLoading] = React.useState(false)
return (
<Spin spinning={loading}>
<SheetComponent onLoading={setLoading} />
</Spin>
)
}
分页组件移除
  1. showPagination 属性移除。
- <SheetComponent showPagination />
  1. 提供 pagination 属性,表格内部封装了 S2 的内部分页更新逻辑,可以配合任意分页组件使用,如 antd 的 <Pagination />。
import { Pagination } from 'antd';
function App() {
return (
<SheetComponent options={s2Options}>
{({ pagination }) => (
// 结合任意分页器使用:如 antd 的 Pagination 组件
<Pagination
size="small"
showTotal={(total) => `共计 ${total} 条`}
{...pagination}
/>
)}
</SheetComponent>
)
}
高级排序组件迁移
- import { AdvancedSort } from '@antv/s2-react';
+ import { AdvancedSort } from '@antv/s2-react-components';
  1. 配置变更

sheet 变更为 sheetInstance

- <AdvancedSort sheet={s2} />
+ <AdvancedSort sheetInstance={s2} />

具体请查看 高级排序 相关文档。

维度切换组件迁移
- import { Switcher } from '@antv/s2-react';
+ import { Switcher } from '@antv/s2-react-components';
  1. 配置变更

新增 icon 配置,title 含义变更,现在不再用做自定义入口,使用 children 代替。

- <Switcher title={<Button>切换维度</Button>} />
+ <Switcher title="切换维度" icon={<SwapOutlined/>} />
+ <Switcher>
+ <Button>切换维度</Button>
+ </Switcher>

具体请查看 维度切换 相关文档。

导出组件迁移
- import { Export } from '@antv/s2-react';
+ import { Export } from '@antv/s2-react-components';
  1. 配置变更
- <Export syncCopy={true} sheet={s2} />
+ <Export async={false} sheetInstance={s2} />

icon 属性移除,支持自定义 children.

- <Export icon={<MoreOutlined/> } />
+ <Export><Button type="text"><MoreOutlined /></Button></Export>
  1. 复制原始数据 和 复制格式化数据 现在会同时将 text/plain 和 text/html 的数据写入到剪贴板。
  2. 新增 onCopySuccess/onCopyError, onDownloadSuccess/onDownloadError API, 移除 successText/errorText, 操作时默认不再显示 message 提示。
<Export
- successText="操作成功"
- errorText="操作成功"
+ onCopySuccess={(data) => {
+ console.log('copy success:', data);
+ }}
+ onCopyError={(error) => {
+ console.log('copy failed:', error);
+ }}
+ onDownloadSuccess={(data) => {
+ console.log('download success', data);
+ }}
+ onDownloadError={(error) => {
+ console.log('download failed:', error);
+ }}
/>
  1. 新增 StrategyExport 组件,适用于趋势分析表的数据复制和导出,使用方式和 Export 相同。
import { StrategyExport } from '@antv/s2-react-components';

具体请查看 导出 相关文档。

维度下钻组件迁移
- import { DrillDown } from '@antv/s2-react';
+ import { DrillDown } from '@antv/s2-react-components';
  1. 配置调整。
- <DrillDown titleText="下钻" clearButtonText="清除" />
+ <DrillDown title="下钻" clearText="清除" />
  1. 在表格组件中使用时,需要通过 render 属性传入 DrillDown 配置面板。
+ import { DrillDown } from '@antv/s2-react-components';
function App() {
return (
<SheetComponent
sheetType="pivot"
options={s2Options}
partDrillDown={{
+ render: (props) => <DrillDown {...props} />,
}}
/>
)
}

具体请查看 维度下钻 相关文档。

编辑表输入框组件替换

antd 的 Input.TextArea 组件替换为 原生的 textarea.

+ <Input.TextArea />
- <textarea />
Tooltip 操作项默认菜单组件移除
  1. 内部排序菜单和操作项依赖的 antd Menu 组件 移除,现在需要通过 render 显式声明 UI 组件,最终效果相同,默认提供菜单配置 (props) , 可以根据项目中实际使用的 antd@v4 或 antd@v5 不同版本,对使用方式进行调整。
import { Menu } from 'antd'
const s2Options = {
tooltip: {
operation: {
menu: {
render: (props) => {
return <Menu {...props} />;
},
}
}
}
}
  1. 配置和 API 参数调整

菜单项调整到 menu 下

const s2Options = {
tooltip: {
operation: {
- onClick: (cell) => {},
- menus: [
- {
- key: 'custom-a',
- text: '操作 1',
- icon: 'Trend',
- onClick: (cell) => {},
- visible: (cell) => true,
- children: [],
- }
- ],
+ menu: {
+ onClick: (info, cell) => {},
+ items: [
+ {
+ key: 'custom-a',
+ label: '操作 1',
+ icon: 'Trend',
+ onClick: (info, cell) => {},
+ visible: (info, cell) => true,
+ children: [],
+ }
+ ],
+ },
},
},
};
<SheetComponent options={s2Options} />

同时,通过 API 方式调用时,defaultSelectedKeys 变更为 selectedKeys。

s2.showTooltip({
options: {
operator: {
menu: {
- defaultSelectedKeys: ['key-1'],
+ selectedKeys: ['key-1'],
},
},
},
});

具体请查看 Tooltip 和 组内排序 相关文档。

支持 React 18

提示

React 19 已发布 RC 版本, 后续兼容视情况而定。

@antv/s2-react 的 2.x 版本适配了 React 18, 并兼容 React 16 和 17.

Ant Design 多版本共存 (不推荐)

由于 [email protected] 已经 停止维护, 分析组件 @antv/s2-react-components 默认基于 [email protected] 开发,虽然使用的都是基础组件,但是是否完全兼容 [email protected] 取决于两个版本的差异性。

对于项目使用的是 [email protected], 或者所依赖的其他库间接依赖 [email protected], 由于种种历史原因无法升级到 [email protected] 的情况,可以通过 多版本共存 的方式来临时过渡。

// $ npm install --save antd-v5@npm:antd@5
{
"antd": "4.x",
"antd-v5": "npm:antd@5"
}

通过 webpack 内置插件 NormalModuleReplacementPlugin 或者 自定义 webpack 插件 的方式指定 @antv/s2-react-components 使用 antd-v5, 无需做任何修改,项目中其他依赖将继续使用 [email protected].

注意

其他打包工具 (如 Vite) 或者基于 webpack 封装的库或框架(如 father, umi) 同理,请自行搜索,这里不再赘述。 需要注意的是:这种方式为临时过渡解决方案,从长远来看,Ant Design v4 版本已于 2023 年年底停止维护,建议尽快升级至 [email protected].

自定义 webpack 插件参考:

class AntdV5AliasPlugin {
apply(compiler) {
compiler.hooks.normalModuleFactory.tap("AntdV5AliasPlugin", (nmf) => {
nmf.hooks.beforeResolve.tapAsync("AntdV5AliasPlugin", (resolveData, callback) => {
if (resolveData.contextInfo?.issuer?.includes('node_modules/@antv/s2-react-components')) {
// 匹配:"antd" 和 "antd/es/locale/xxx"
if (/antd(\/*)?/.test(resolveData.request)) {
// 替换为:"antd-v5" 和 "antd-v5/es/locale/xxx"
resolveData.request = resolveData.request.replace(/antd(\/*)?/,'antd-v5$1')
}
}
callback();
});
});
}
}

行头单元格折叠展开事件划分到 RowCell

onCollapseRowsAll, onLayoutAfterCollapseRows 更名为 onRowCellAllCollapsed, onRowCellCollapsed

- <SheetComponent options={s2Options} onCollapseRowsAll={} />
+ <SheetComponent options={s2Options} onRowCellAllCollapsed={} />
- <SheetComponent options={s2Options} onLayoutAfterCollapseRows={} />
+ <SheetComponent options={s2Options} onRowCellCollapsed={} />

onSheetUpdate 更名为 onUpdate, 并新增 onUpdateAfterRender

  • onUpdate: 组件层表格更新事件,当 数据 (S2DataConfig) 或 配置 (S2Options) 更新时触发。
  • onUpdateAfterRender: 组件层表格更新事件,当 数据 (S2DataConfig) 或 配置 (S2Options) 更新时,并且在重渲染 s2.render() 完成后触发。
- <SheetComponent onSheetUpdate={} />
+ <SheetComponent onUpdate={} onUpdateAfterRender={} />

onUpdate 类型优化,不再强制要求返回渲染参数

2.x 版本中,onUpdate 如未指定渲染参数,则使用默认的 renderOptions.

<SheetComponent
onUpdate={(renderOptions) => {
- return renderOptions
}}
/>

SheetComponentsProps 类型调整

- interface SheetComponentsProps {}
+ interface SheetComponentProps {}

组件层 (s2-vue) @antv/s2-vue 停止维护

注意

@antv/s2-vue 现已停止维护,由于精力投入有限,出于维护成本,包下载量等因素综合考虑,从 2.0.0 正式版后不再继续更新,请基于 @antv/s2 自行封装,或 fork 仓库进行二次开发社区版本。

✍️ API 调整

具体请查看标记为 New 和 Updated 的 API 文档

🙋 遇到问题

更多新特性和改动请阅读文档,如果您在升级过程中遇到了问题,请到 GitHub issues 或者 GitHub Discussions 进行反馈。我们会尽快响应和改进这篇文档。