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

Interaction

上一篇
SpreadSheet
下一篇
Store

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.interaction.reset()
参数说明类型
spreadsheet表格实例SpreadSheet
interactions当前已注册的交互Map<string, BaseEvent>
intercepts当前拦截的交互,防止不同交互之间冲突 (查看示例)Set<Intercept>
eventController事件控制器EventController
destroy卸载所有交互实例,并重置为初始状态() => void
reset重置所有交互() => void
setState设置状态(data: InteractionStateInfo) => void
getState获取当前状态() => void
resetState重置为初始状态() => void
clearState清空状态,并重绘() => void
changeState更新状态(data: InteractionStateInfo) => void
setInteractedCells设置当前发生改变的单元格(cell: S2CellType) => void
getInteractedCells获取当前发生改变的单元格() => S2CellType[]
getCurrentStateName获取当前状态名() => void
isEqualStateName是否是相同的状态名(name: InteractionStateName) => boolean
isSelectedState是否是选中状态() => boolean
isBrushSelectedState是否是刷选状态() => boolean
isHoverState是否是悬停状态() => boolean
isHoverFocusState是否是悬停聚焦状态 (悬停在单元格 focusTime: 默认 800ms 后)() => boolean
isSelectedCell是否是选中的单元格(cell: S2CellType) => boolean
isActiveCell是否是激活的单元格(cell: S2CellType) => boolean
getCells获取当前 interaction 记录的 Cells 元信息列表,包括不在可视范围内的单元格() => Partial<ViewMeta>[]
getActiveCells获取当前在可视区域的单元格实例() => S2CellType[]
clearStyleIndependent清除单元格交互样式() => void
getActiveDataCells获取当前在可视区域的数值单元格实例() => S2CellType[]
getActiveRowCells获取当前在可视区域的行头单元格实例() => S2CellType[]
getActiveColCells获取当前在可视区域的列头单元格实例() => S2CellType[]
clearStyleIndependent清除单元格样式() => void
getUnSelectedDataCells获取可视区域内选中的数值单元格() => DataCell[]
getAllCells获取所有可视区域内的单元格() => S2CellType[]
selectAll选中所有单元格() => void
hideColumns隐藏列 (forceRender 为 false 时,隐藏列为空的情况下,不再触发表格更新)(hiddenColumnFields: string[], forceRender?: boolean = true) => void
mergeCells合并单元格(cellsInfo?: MergedCellInfo[], hideData?: boolean) => void
unmergeCell取消合并单元格(removedCell: MergedCell) => void
updateAllDataCells更新所有数值单元格() => void
updateCells更新指定单元格(cells: S2CellType[]) => void
addIntercepts新增交互拦截(interceptTypes: InterceptType[]) => void
hasIntercepts是否有指定拦截的交互(interceptTypes: InterceptType[]) => boolean
removeIntercepts移除指定交互拦截(interceptTypes: InterceptType[]) => void
highlightNodes高亮节点对应的单元格(nodes: Node[], stateName: InteractionStateName) => void
scrollTo滚动至指定位置(offsetConfig: ScrollOffsetConfig) => void
scrollToNode滚动至指定单元格节点(node: Node, options?: CellScrollToOptions) => void
scrollToCell滚动至指定单元格(cell: S2CellType, options?: CellScrollToOptions) => void
scrollToCellById滚动至指定单元格 id 对应的位置,如果不在可视化范围内,则会自动滚动(id: string, options?: CellScrollToOptions) => void
scrollToTop滚动至顶部(options?: CellScrollToOptions) => void
scrollToRight滚动至右边(options?: CellScrollToOptions) => void
scrollToBottom滚动至底部(options?: CellScrollToOptions) => void
scrollToLeft滚动至左边(options?: CellScrollToOptions) => void
highlightCell高亮指定单元格(可视范围内)(cell: S2CellType) => void
selectCell选中指定单元格(可视范围内)(cell: S2CellType, options: ChangeCellOptions) => void
changeCell改变指定单元格状态(可视范围内)(如:选中/高亮/多选等)(cell: S2CellType, options: ChangeCellOptions) => void
updateDataCellRelevantHeaderCells高亮数值单元格和所对应行列单元格(stateName: InteractionStateName, meta: ViewMeta) => void
updateDataCellRelevantRowCells高亮数值单元格和所对应行头单元格(stateName: InteractionStateName, meta: ViewMeta) => void
updateDataCellRelevantColCells高亮数值单元格和所对应列头单元格(stateName: InteractionStateName, meta: ViewMeta) => void

Interaction

功能描述:交互配置。查看 文档 和 示例

参数说明类型默认值必选
linkFields标记字段为链接样式,用于外链跳转string[] | (meta: Node | ViewMeta) => boolean
selectedCellsSpotlight是否开启选中高亮聚光灯效果booleanfalse
hoverHighlight鼠标悬停时高亮当前单元格,以及所对应的行头,列头booleantrue
hoverFocus鼠标悬停在当前单元格超过默认 800ms 后,保持当前高亮,显示 tooltip,悬停时间通过设置 duration 来控制boolean | {duration: number}true
hiddenColumnFields用于配置默认隐藏的列,透视表 和多列头明细表 需要配置列头唯一 id, 单列头明细表 配置列头 field 字段即可 (即:s2DataConfig.fields.columns). 了解更多string[]
copy单元格复制配置Copy
customInteractions自定义交互 详情CustomInteraction[]
scrollSpeedRatio用于控制滚动速率,分水平和垂直两个方向,默认为 1ScrollSpeedRatio
autoResetSheetStyle用于控制点击表格外区域和按下 ESC 键时是否重置交互状态和关闭 Tooltip, 支持根据 event 动态判断boolean | (event: Event | FederatedPointerEvent, spreadsheet: SpreadSheet) => booleantrue
resize用于控制 resize 热区是否显示boolean | ResizeInteractionOptionstrue
brushSelection是否允许单元格(包含行头,列头,数值单元格)刷选。行头,列头刷选只支持透视表boolean | BrushSelectiontrue
multiSelection是否允许多选 (包含行头,列头,数值单元格)booleantrue
rangeSelection是否允许区间快捷多选booleantrue
scrollbarPosition用于控制滚动条展示在内容区边缘还是画布边缘content | canvascontent
eventListenerOptions事件监听函数 addEventListener 的 可选项配置, 可控制事件从冒泡阶段还是捕获阶段触发false
selectedCellHighlight选中数值单元格后的行列高亮联动
rowHeader:选中数值单元格后高亮对应行头
colHeader:选中数值单元格后高亮对应列头
currentRow:选中数值单元格后高亮整行
currentCol:选中数值单元格后高亮整列
true:同 { rowHeader: true, colHeader: true, currentRow: true, currentCol: true }
boolean | { rowHeader?: boolean, colHeader?: boolean, currentRow?: boolean, currentCol?: boolean }false
overscrollBehavior控制滚动至边界的行为,可禁用浏览器的默认滚动行为。详情auto | contain | none | nullauto

Copy

功能描述:单元格复制。查看 文档 和 示例

参数说明类型默认值必选
enable是否允许复制booleantrue
withFormat是否使用 s2DataConfig 的 formatter 格式复制数据booleantrue
withHeader复制数据是否带表头信息booleanfalse
customTransformer复制时支持自定义 (transformer) 数据格式化方法(transformer: Transformer) => Partial<Transformer>transformer

CustomInteraction

功能描述:自定义交互,继承 BaseEvent: 查看示例

参数说明类型默认值必选
key交互的唯一标识string✓
interaction交互实例InteractionConstructor✓

ScrollSpeedRatio

功能描述:滚动速率配置。查看示例

interface ScrollSpeedRatio {
horizontal?: number; // 水平滚动速率,默认为 1
vertical?: number; // 垂直滚动速率,默认为 1
}

ResizeInteractionOptions

功能描述:宽高调整配置。查看示例

参数说明类型默认值必选
rowCellVertical是否开启行头垂直方向 resize 热区booleantrue
cornerCellHorizontal是否开启角头水平方向 resize 热区booleantrue
colCellHorizontal是否开启列头水平方向 resize 热区booleantrue
colCellVertical是否开启列头垂直方向 resize 热区 (列头隐藏时该配置无效)booleantrue
rowResizeType用于控制行高 resize 时的生效范围
1. all: 对所有单元格生效(会覆盖默认的行高配置),2. current: 对当前单元格生效,3. selected: 对当前单元格生效,如果单元格是多选状态,调整任意选中单元格,对所有选中的生效。
all| current | selectedcurrent
colResizeType用于控制列宽 resize 时的生效范围
1. all: 对所有单元格生效(会覆盖默认的列宽配置),2. current: 对当前单元格生效,3. selected: 对当前单元格生效,如果单元格是多选状态,调整任意选中单元格,对所有选中的生效。
all| current | selectedcurrent
disable用于控制行高 resize 是否生效。查看示例(resizeInfo: S2CellType) => boolean
visible自定义当前单元格是否显示 resize 热区(cell: S2CellType) => boolean
minCellWidth单元格可拖拽最小宽度number40
minCellHeight单元格可拖拽最小高度number20

BrushSelection

功能描述:单元格刷选配置。查看示例

参数说明类型默认值必选
dataCell是否允许数值单元格刷选booleantrue
rowCell是否允许行头单元格刷选(仅支持透视表)booleanfalse
colCell是否允许列头单元格刷选booleanfalse

CellSelectedDetail

功能描述:单元格选中信息明细。

参数说明类型默认值必选
interactionName触发选中的交互名InteractionName
targetCell触发选中的单元格S2CellType
event触发选中的事件对象FederatedPointerEvent | Event | KeyboardEvent

InterceptType

功能描述:交互拦截类型。

enum InterceptType {
HOVER = 'hover',
CLICK = 'click',
DATA_CELL_BRUSH_SELECTION = 'dataCellBrushSelection',
ROW_CELL_BRUSH_SELECTION = 'rowCellBrushSelection',
COL_CELL_BRUSH_SELECTION = 'colCellBrushSelection',
MULTI_SELECTION = 'multiSelection',
RESIZE = 'resize',
}

InteractionName

功能描述:交互名称。

enum InteractionName {
CORNER_CELL_CLICK = 'cornerCellClick',
DATA_CELL_CLICK = 'dataCellClick',
ROW_CELL_CLICK = 'rowCellClick',
COL_CELL_CLICK = 'colCellClick',
MERGED_CELLS_CLICK = 'mergedCellsClick',
ROW_COLUMN_CLICK = 'rowColumnClick',
HEADER_CELL_LINK_CLICK = 'headerCellLinkClick',
HOVER = 'hover',
DATA_CELL_BRUSH_SELECTION = 'dataCellBrushSelection',
ROW_CELL_BRUSH_SELECTION = 'rowCellBrushSelection',
COL_CELL_BRUSH_SELECTION = 'colCellBrushSelection',
COL_ROW_RESIZE = 'rowColResize',
DATA_CELL_MULTI_SELECTION = 'dataCellMultiSelection',
ROW_CELL_MULTI_SELECTION = 'rowCellMultiSelection',
COL_CELL_MULTI_SELECTION = 'colCellMultiSelection',
RANGE_SELECTION = 'rangeSelection',
SELECTED_CELL_MOVE = 'selectedCellMove',
GLOBAL_RESET = 'globalReset',
}

InteractionStateName

功能描述:交互状态名称。

enum InteractionStateName {
ALL_SELECTED = 'allSelected',
SELECTED = 'selected',
ROW_CELL_BRUSH_SELECTED = 'rowCellBrushSelected',
COL_CELL_BRUSH_SELECTED = 'colCellBrushSelected',
DATA_CELL_BRUSH_SELECTED = 'dataCellBrushSelected',
UNSELECTED = 'unselected',
HOVER = 'hover',
HOVER_FOCUS = 'hoverFocus',
HIGHLIGHT = 'highlight',
SEARCH_RESULT = 'searchResult',
PREPARE_SELECT = 'prepareSelect',
}

CellType

功能描述:单元格类型。

enum CellType {
DATA_CELL = 'dataCell',
ROW_CELL = 'rowCell',
COL_CELL = 'colCell',
SERIES_NUMBER_CELL = 'seriesNumberCell',
CORNER_CELL = 'cornerCell',
MERGED_CELL = 'mergedCell',
}

CellScrollToOptions

export interface CellScrollToOptions {
/**
* 是否展示滚动动画
*/
animate?: boolean;
/**
* 是否触发滚动事件
*/
skipScrollEvent?: boolean;
}

ChangeCellOptions

export interface ChangeCellOptions {
/**
* 目标单元格
*/
cell: S2CellType<ViewMeta>;
/**
* 是否是多选
*/
isMultiSelection?: boolean;
/**
* 状态名 (默认 `selected`)
*/
stateName?: InteractionStateName;
/**
* 如果单元格不在可视范围,是否自动滚动
*/
scrollIntoView?: boolean;
}

ScrollOffsetConfig

export interface ScrollOffsetConfig {
skipScrollEvent?: boolean;
rowHeaderOffsetX?: {
value: number | undefined;
animate?: boolean;
};
offsetX?: {
value: number | undefined;
animate?: boolean;
};
offsetY?: {
value: number | undefined;
animate?: boolean;
};
}

ScrollOffset

export interface ScrollOffset {
scrollX?: number;
scrollY?: number;
rowHeaderScrollX?: number;
}

InteractionConstructor

export type InteractionConstructor = new (
spreadsheet: SpreadSheet,
) => BaseEvent;

BaseEvent

export abstract class BaseEvent {
public spreadsheet: SpreadSheet;
constructor(spreadsheet: SpreadSheet) {
this.spreadsheet = spreadsheet;
this.bindEvents();
}
public abstract bindEvents(): void;
}

S2CellType

type S2CellType<T extends SimpleBBox = ViewMeta> =
| DataCell
| HeaderCell
| ColCell
| CornerCell
| RowCell
| SeriesNumberCell
| MergedCell
| TableDataCell
| TableCornerCell
| TableSeriesNumberCell
| BaseCell<T>;

ChangeCellOptions

interface ChangeCellOptions {
/**
* 目标单元格
*/
cell: S2CellType<ViewMeta>;
/**
* 是否是多选
*/
isMultiSelection?: boolean;
/**
* 状态名
*/
stateName?: InteractionStateName;
/**
* 交互名
*/
interactionName?: `${InteractionName}`;
/**
* 如果单元格不在可视范围,是否自动滚动
*/
scrollIntoView?: boolean;
}

MergedCellInfo

interface MergedCellInfo {
colIndex?: number;
rowIndex?: number;
showText?: boolean;
}

CellMeta

interface CellMeta {
id: string;
colIndex: number;
rowIndex: number;
type: CellType;
rowQuery?: Record<string, any>;
[key: string]: unknown;
}

InteractionStateInfo

interface InteractionStateInfo {
stateName?: InteractionStateName;
cells?: CellMeta[];
interactedCells?: S2CellType[];
nodes?: Node[];
force?: boolean;
}

EventController

参数说明类型
spreadsheet表格实例SpreadSheet
canvasEventHandlers当前已注册的交互EventHandler[]
s2EventHandlers当前已注册的交互S2EventHandler[]
domEventListeners当前已注册的交互EventHandler[]
isCanvasEffect是否是图表内部引起的事件boolean
canvasMousemoveEvent表格鼠标移动事件FederatedPointerEvent
isMatchElement是否是表格内部的元素(event: MouseEvent) => boolean
isMatchPoint是否是表格内部的坐标(event: MouseEvent) => boolean
bindEvents绑定交互事件() => void
clear清空交互事件() => void
getViewportPoint获取表格内的鼠标坐标 (兼容 supportsCSSTransform)(event: MouseEvent | PointerEvent | WheelEvent) => PointLike

EventListener

interface EventListener {
target: EventTarget;
type: string;
handler: EventListenerOrEventListenerObject;
options?: AddEventListenerOptions | boolean;
}

S2EventHandler

interface S2EventHandler {
type: keyof EmitterType;
handler: EmitterType[keyof EmitterType];
}

EventHandler

interface EventHandler {
type: string;
handler: (event: FederatedPointerEvent) => void;
}

ViewMeta

功能描述:数值单元格数据和位置等信息

参数类型必选默认值功能描述
spreadsheetSpreadSheet表格实例
idstring单元格唯一标识
xnumber单元格 x 坐标
ynumber单元格 y 坐标
widthnumber单元格宽度
heightnumber单元格高度
dataViewMetaData单元格数据
rowIndexnumber单元格在行叶子节点中的索引
colIndexnumber单元格在列叶子节点中的索引
valueFieldstring度量 id
fieldValueDataItem度量展示的真实值
isTotalsboolean 是否为总计:true 为总计 false 为小计
queryRecord<string, any>行列查询条件
rowQueryRecord<string, any>行查询条件
colQueryRecord<string, any>列查询条件
rowIdstring单元格的行 id
colIdstring单元格的列 id

RawData

DateItem
type RawData = Record<string, DataItem>;

SimpleData

type SimpleData = string | number | null | undefined;

MultiData

功能描述:用于支持多指标类型的自定义数据单元格渲染。例如:趋势分析表

配置项名称说明类型默认值必选
values格式化后的数据,直接展示在 dataCfg 中SimpleData[][]✓
originalValues原始数据,用于原始数据导出SimpleData[][]
label用作单元格小标题,单独占一行展示string
[key: string]其他透传字段,用于自定义单元格的定制化展示unknown``
{
"number": {
"originalValues": [1, 2, 3],
"values": ["1", "2", "3"]
}
}

DataItem

SimpleData | MultiData | MiniChartData

type DataItem = SimpleData | MultiData | MiniChartData | Record<string, unknown>;
{
"number": 7789,
"province": "浙江省",
"city": "杭州市",
"type": "家具",
"sub_type": "桌子"
}

ExtraData

import type { EXTRA_FIELD, VALUE_FIELD } from '@antv/s2';
type ExtraData = {
[EXTRA_FIELD]: string;
[VALUE_FIELD]: string | DataItem;
};
{
"$$extra$$": "number",
"$$value$$": 7789,
}

Data

type Data = RawData & ExtraData;

ViewMetaData

查看 CellData 定义
type ViewMetaData = Data | CellData;

Data

{
"city": "杭州市"
}

CellData

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

MiniChartData

功能描述:在单元格内绘制 mini 图(支持 折线图、子弹图、柱状图). 查看 文档 和 示例

BaseChartData

功能描述:内置折线图、柱状图数据配置项,数据格式参考 G2

参数说明类型必选默认值
typemini 图类型line | bar✓
encode编码方式,声明 x 位置通道或 y 位置通道绑定的对应的列数据{x: string; y: string}✓
data原始数据Data[]✓
[key: string]其他透传字段,用于自定义单元格的定制化展示unknown

BulletValue

功能描述:内置子弹图数据配置项

参数说明类型必选默认值
typemini 图类型bullet✓bullet
measure当前指标number | string✓
target目标值number | string✓
[key: string]其他透传字段,用于自定义单元格的定制化展示unknown