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

交互种类

表格常见的交互主要通过键盘和鼠标

  • 鼠标点击 (click)
  • 鼠标悬停 (hover)
  • 键盘按下/弹起 (keydown / keyup)
  • ...

通过这些事件,排列组合,来实现常用的交互, 以 刷选 为例,它由三个事件组成

  • mousedown => mousemove => mouseup

内置交互

名称事件名描述
单选S2Event.GLOBAL_SELECTED单击单元格,弹出 tooltip, 展示对应单元格的信息,再次单击取消选中
多选S2Event.GLOBAL_SELECTED单选单元格后,按住 Command / Ctrl 键,继续单选
行/列头快捷多选S2Event.GLOBAL_SELECTED单击行/列头,选中对应行/列头所有单元格 (含不在可视范围内的), 再次单击取消选中
行/列头手动调整宽高S2Event.LAYOUT_RESIZE鼠标悬浮在行/列头单元格边缘,出现指示条和光标,按住鼠标左键拖动,调整宽高
刷选S2Event.DATA_CELL_BRUSH_SELECTION S2Event.GLOBAL_SELECTED批量选中刷选范围内的数值单元格,刷选过程中,显示刷选范围提示蒙层,刷选完成后,弹出 tooltip, 展示被刷选单元格信息和数量
行头刷选S2Event.ROW_CELL_BRUSH_SELECTION S2Event.GLOBAL_SELECTED批量选中刷选范围内的行头单元格,刷选过程中,显示刷选范围提示蒙层,刷选完成后,弹出 tooltip, 展示被刷选单元格信息(仅支持透视表)
列头刷选S2Event.COL_CELL_BRUSH_SELECTION S2Event.GLOBAL_SELECTED批量选中刷选范围内的列头单元格,刷选过程中,显示刷选范围提示蒙层,刷选完成后,弹出 tooltip, 展示被刷选单元格信息
区间快捷多选S2Event.GLOBAL_SELECTED单选单元格 (start), 然后按住 Shift 再次选中一个单元格 (end), 选中两个单元格区间所有单元格
悬停S2Event.GLOBAL_HOVER鼠标悬停时,对应单元格高亮展示,如果是数值单元格,则默认 十字高亮,可设置 hoverHighlight: false 关闭
复制S2Event.GLOBAL_COPIED复制选中的单元格数据
隐藏列头S2Event.COL_CELL_EXPANDED S2Event.COL_CELL_HIDDEN隐藏/展开 列头
列头展开按钮悬停S2Event.COL_CELL_EXPAND_ICON_HOVER鼠标悬浮在列头展开按钮上时触发,可以获取当前位置所有隐藏列
链接跳转S2Event.GLOBAL_LINK_FIELD_JUMP行头/列头/数值 链接跳转
重置S2Event.GLOBAL_RESET再次点击,点击空白处,或按下 Esc 取消选中的单元格
移动高亮单元格S2Event.GLOBAL_SELECTED点击数值单元格后,使用键盘方向键即可移动当前高亮单元格

交互事件

查看完整事件列表
  • global:xx: 全局图表事件
  • layout:xx: 布局改变事件
  • cell:xx: 单元格级别的事件,整个表格分为不同的单元格类型,你可以对特定的单元格进行事件监听,实现自定义需求
import { ColCell, DataCell, PivotSheet, RowCell, S2Event } from '@antv/s2';
const s2 = new PivotSheet(container, s2DataConfig, s2Options);
s2.on(S2Event.DATA_CELL_BRUSH_SELECTION, (cells: DataCell[]) => {
// 此事件默认打开,配置 options: { interaction: { brushSelection : { dataCell: true } } } 开启数值单元格刷选
console.log('刷选的单元格', cells)
})
s2.on(S2Event.ROW_BRUSH_SELECTION, (cells: RowCell[]) => {
// 此事件默认关闭,配置 options: { interaction: { brushSelection : { rowCell: true } } } 开启行头单元格刷选
console.log('刷选的行头单元格:', cells)
})
s2.on(S2Event.COL_BRUSH_SELECTION, (cells: ColCell[]) => {
// 此事件默认关闭,配置 options: { interaction: { brushSelection : { colCell: true } } } 开启列头单元格刷选
console.log('刷选的列头单元格:', cells)
})
s2.on(S2Event.COL_CELL_HOVER, (event) => {
...
})
s2.on(S2Event.GLOBAL_KEYBOARD_DOWN, (event) => {
...
})

如果使用的是 @antv/s2-react 或 @antv/s2-vue, 可以拿到 S2 表格实例 后对所需事件进行监听,和 @antv/s2 使用方式完全一致 .

import { S2Event, SpreadSheet } from '@antv/s2'
import { SheetComponent } from '@antv/s2-react';
function App() {
const s2Ref = React.useRef<SpreadSheet>();
const onSheetMounted = () => {
s2Ref.current?.on(S2Event.DATA_CELL_CLICK, (event) => {
console.log('onDataCellClick: ', event)
})
}
return <SheetComponent ref={s2Ref} onMounted={onSheetMounted}/>
}

同时 React, Vue3 版本提供了事件的隐射,也可以方便的使用更符合使用习惯的 onDataCellClick, @dataCellClick 的方式 (查看所有 API)

React

import { SheetComponent } from '@antv/s2-react';
const onDataCellClick = () => {}
<SheetComponent onDataCellClick={onDataCellClick} />

Vue

import { SheetComponent } from '@antv/s2-vue';
const onDataCellClick = () => {}
<SheetComponent @dataCellClick={onDataCellClick} />

对于全局图表事件,底层通过浏览器的 EventTarget.addEventListener() API 实现,如需配置其第三个可选参数,可通过 eventListenerOptions 进行透传,从而控制事件从 冒泡阶段 还是 捕获阶段 触发,或者只触发一次等配置。

const s2Options = {
interaction: {
eventListenerOptions: {
capture: true,
}
}
}
// 等价于
window.addEventListener('mouseup', () => {}, {
capture: true,
})
window.addEventListener('mouseup', () => {}, true)

交互相关配置

查看具体 API 配置详情
const s2Options = {
interaction: {
...
}
}

内置交互

如何修改交互默认样式?请查看 主题配置 章节

单选高亮

preview

在选中单元格后,如果需要置灰未选中的单元格,强调需要关注的数据,默认关闭,可配置 selectedCellsSpotlight 开启:

const s2Options = {
interaction: {
selectedCellsSpotlight: true, // 默认 false
}
};
查看示例

行列联动高亮

在鼠标悬停时,高亮当前单元格和对应的行列头单元格,形成一个"十字高亮"的效果,更直观的查看数据,默认开启,可配置 hoverHighlight 关闭:

preview
const s2Options = {
interaction: {
hoverHighlight: false // 默认 true
// 等同于
// hoverHighlight: {
// rowHeader = false, // 高亮悬停格子所在行头
// colHeader = false, // 高亮悬停格子所在列头
// currentRow = false, // 高亮悬停格子所在行
// currentCol = false, // 高亮悬停格子所在列
// },
}
};
查看示例

单选后行列头高亮

在鼠标选中单元格或刷选选中单元格时,高亮当前单元格对应的行列头单元格,利于快速定位单元格所在行列。默认关闭,可配置 selectedCellHighlight 开启:

preview
// selectedCellHighlight 的类型为 boolean | { rowHeader: boolean, colHeader: boolean, rowCells: boolean, colCells: boolean }
// 当 selectedCellHighlight 为 boolean 时
const s2Options = {
interaction: {
selectedCellHighlight: true // 默认 false, 当 selectedCellsSpotlight 为 true 时,会高亮 rowHeader 和 colHeader (兼容未拓展类型前的设计)
}
};
// 同时还可以分别配置 selectedCellHighlight 中 header 和 cells 的高亮
const s2Options = {
interaction: {
selectedCellHighlight: {
rowHeader: true, // 选中单元格时,高亮行头
colHeader: true, // 选中单元格时,高亮列头
currentRow: true, // 选中单元格时,高亮当前行
currentCol: true, // 选中单元格时,高亮当前列
},
},
};
查看示例

悬停聚焦

鼠标悬停在当前单元格超过 800ms 后,保持当前高亮,显示 tooltip, 聚焦于当前数据,默认开启,可配置 hoverFocus 关闭,也可配置 hoverFocus.duration 更改出现 tooltip 的时间间隔。如果希望 hover 后立刻出现 tooltip,可以设置 duration 为 0;

如果你实现了自定义交互,如 hover 后显示 tooltip, 推荐关闭此功能,以免出现 hover 悬停后 tooltip 被意外关闭

preview
const s2Options = {
interaction: {
hoverFocus: false // 默认 true
}
};

圈选

圈选又叫刷选,刷选过程中,会提示预选中的单元格,并且显示半透明的刷选蒙层,支持对 数据单元格 (dataCell), 行头单元格 (rowCell), 列头单元格 (colCell) 进行圈选,同时支持 滚动圈选, 可以用来做 统计数据总和, 单元格个数, 复制选定数据 等操作,默认开启 数据单元格,可配置 brushSelection 关闭:

数据单元格圈选

preview
const s2Options = {
interaction: {
brushSelection: false
// 等同于:
// brushSelection: {
// row: false,
// col: false,
// data: false,
// }
}
};
查看示例

行头单元格圈选

preview
const s2Options = {
interaction: {
brushSelection: {
rowCell: true // 默认 false
}
}
};
查看示例

列头单元格圈选

preview
const s2Options = {
interaction: {
brushSelection: {
colCell: true // 默认 false
}
}
};
查看示例

滚动圈选

数值滚动圈选
preview
行头滚动圈选
preview

角头选中

单击行头所对应的角头,可以快捷选中当前列

preview

快捷键多选

(Command/Ctrl) + click: 单个多选叠加,再次点击选中的单元格或行列可取消选中,默认开启,可配置 multiSelection 关闭:

preview

Shift + click: 区间选择(类似刷选), 默认开启,可配置 rangeSelection 关闭:

preview
const s2Options = {
interaction: {
multiSelection: false, // 默认 true
rangeSelection: false // 默认 true
}
};
查看示例

移动高亮单元格

点击数值单元格后,使用键盘方向键即可移动当前高亮单元格,默认开启,可配置 selectedCellMove 关闭:

preview
const s2Options = {
interaction: {
selectedCellMove: false // 默认 true
}
};
查看示例

隐藏列头

preview

同时支持透视表,和明细表,点击叶子节点的列头后,显示隐藏列头按钮,点击隐藏后,会在紧邻的兄弟单元格显示一个展示按钮,和一个隐藏提示线,鼠标单击即可展开,可配置 hiddenColumns 实现 默认隐藏 和 交互式隐藏. 查看 详情 或 示例

const s2DataConfig = {
fields: {
columns: ['fieldA', 'fieldB']
}
}
const s2Options = {
interaction: {
// 默认隐藏
hiddenColumns: ['fieldA']
},
// 关闭手动隐藏
tooltip: {
operation: {
hiddenColumns: false
}
}
};
查看示例

行列宽高调整

preview

查看 文档 和 示例

合并单元格

preview

查看 文档 和 示例

链接跳转

preview

查看 文档 和 示例

滚动

查看 文档

复制与导出

查看 文档

重置交互

preview

支持重置交互的情况:

  • 点击非表格空白处
  • 按下 Esc 键
  • 选中单元格后再次点击

对应事件:GLOBAL_RESET

s2.on(S2Event.GLOBAL_RESET, () => {
console.log('重置')
})

可配置 autoResetSheetStyle 关闭重置交互。查看示例

const s2Options = {
interaction: {
autoResetSheetStyle: false
}
};

也可以根据当前 event 动态判断是否重置,如:点击指定容器或按钮时不自动重置交互。

const s2Options = {
interaction: {
autoResetSheetStyle: (event, spreadsheet) => {
if (event?.target instanceof HTMLElement) {
return !document
.querySelector('.container')
?.contains(event?.target);
}
return true;
},
}
};
查看示例

调整交互主题

可以通过 主题配置 对应的 交互主题, 调整选中/悬停/圈选等交互主题。

查看示例

交互拦截

可以通过自定义屏蔽交互事件,如不响应表格的 hover, click 事件等。

import { InterceptType } from '@antv/s2'
// 添加拦截
s2.interaction.addIntercepts([InterceptType.HOVER, InterceptType.CLICK]);
// 移除拦截
s2.interaction.removeIntercepts([InterceptType.HOVER, InterceptType.CLICK]);
查看示例

调用 API

S2 内置了一些交互相关的 API,统一挂载在 s2.interaction 命名空间下,你可以在拿到 SpreadSheet 实例 后调用它们来实现你的效果,比如 选中所有单元格, 获取列头单元格 等常用方法,具体请查看 Interaction 实例类 和 示例

const s2 = new PivotSheet()
s2.interaction.selectAll()
s2.interaction.selectCell()
s2.interaction.highlightCell()
s2.interaction.changeCell()
查看示例

扩展阅读

对背后的交互实现原理感兴趣?欢迎阅读文章 《你不知道的 Canvas 表格交互》