Interactive type

The common interaction of the form is mainly through the keyboard and mouse

• mouse click
• mouseover (hover)
• Keyboard press/up (keydown / keyup)
• ...

Through these events, permutations and combinations, to achieve commonly used interactions, take刷选as an example, it consists of three events

• mousedown => mousemove => mouseup

built-in interaction

interaction event

• global:xx : global chart events
• layout:xx : layout change event
• cell:xx : Cell-level events, the entire table is divided into different cell types, you can monitor specific cells for events to achieve custom requirements

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) => {
  ...
})

If you are using @antv/s2-react or @antv/s2-vue , you can get the S2 table instance and listen to the required events, which is exactly the same as @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}/>
}

At the same time, React and Vue3 versions provide event mapping, and you can also use onDataCellClick and @dataCellClick methods that are more in line with your habits ( see all APIs )

React

import { SheetComponent } from '@antv/s2-react';

const onDataCellClick = () => {}

<SheetComponent onDataCellClick={onDataCellClick} />

Vue

import { SheetComponent } from '@antv/s2-vue';

const onDataCellClick = () => {}

<SheetComponent @dataCellClick={onDataCellClick} />

For global chart events, the bottom layer is implemented through the browser's EventTarget.addEventListener() API. If you need to configure its third optional parameter, you can pass it through eventListenerOptions to control whether the event is triggered from the冒泡阶段or the捕获阶段, or only Trigger once and so on.

const s2Options = {
  interaction: {
    eventListenerOptions: {
      capture: true,
    }
  }
}

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

window.addEventListener('mouseup', () => {}, true)

Interaction related configuration

const s2Options = {
  interaction: {
    ...
  }
}

built-in interaction

How to modify the interaction default style? Please check the theme configuration chapter

radio highlight

After selecting a cell, if you need to gray out the unselected cells and emphasize the data that needs attention, it is disabled by default, and you can configure selectedCellsSpotlight to enable it:

const s2Options = {
  interaction: {
    selectedCellsSpotlight: true, // 默认 false
  }
};

Row and column linkage highlighting

When the mouse hovers, highlight the current cell and the corresponding row and column header cells to form a "cross highlight" effect, and view the data more intuitively. It is enabled by default and can be configured to hoverHighlight :

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

Row and column headers are highlighted after single selection

When the mouse selects a cell or brushes a selected cell, the row and column head cell corresponding to the current cell is highlighted, which is convenient for quickly locating the row and column of the cell. Disabled by default, you can configure selectedCellHighlight to enable:

// selectedCellHighlight 的类型为  boolean | { rowHeader: boolean, colHeader: boolean, rowCells: boolean, colCells: boolean }
// 当 selectedCellHighlight 为 boolean 时
const s2Options = {
  interaction: {
    selectedCellHighlight: true // default is false
  }
};

// You can also configure the highlighting of header and cells in selectedCellHighlight separately
const s2Options = {
  interaction: {
    selectedCellHighlight: {
      rowHeader: true,  // Highlight row header when cell is selected
      colHeader: true,  // Highlight column header when cells are selected
      currentRow: false,  // Highlight the current row when a cell is selected
      currentCol: false,  // Highlight the current column when a cell is selected
    },
  },
};

hover focus

After the mouse hovers over the current cell for more than 800ms , it will keep the current highlight, display the tooltip , and focus on the current data. It is enabled by default. You can configure hoverFocus to turn it off, and you can also configure hoverFocus.duration to change the time interval for the tooltip to appear. If you want the tooltip to appear immediately after hover, you can set the duration to 0;

If you implement a custom interaction, such as displaying a tooltip after hover, it is recommended to turn off this function, so as not to accidentally close the tooltip after hovering

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

circle highlight

Circle selection highlighting is also called brush selection. During the brush selection process, the pre-selected cells will be prompted and a translucent brush selection mask will be displayed. It is enabled by default and can be configured to brushSelection :

Data cell circle selection

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

Row header cell circle selection

const s2Options = {
  interaction: {
    brushSelection:  {
        rowCell: true // 默认 false
    }
  }
};

Column header cell circle selection

const s2Options = {
  interaction: {
    brushSelection:  {
        colCell: true // 默认 false
    }
  }
};

shortcut key multiple selection

(Command/Ctrl) + click: Single multi-selection overlay, click the selected cell or row or column again to unselect it, it is enabled by default, and multiSelection can be configured to disable:

Shift + click: range selection (similar to brush selection), enabled by default, and can be configured to rangeSelection :

const s2Options = {
  interaction: {
    multiSelection: false, // 默认 true
    rangeSelection: false // 默认 true
  }
};

move highlighted cell

After clicking the value cell, use the keyboard arrow keys to move the current highlighted cell, which is enabled by default, and can be configured to disable selectedCellMove :

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

hide column header

Both pivot tables and detailed tables are supported. After clicking the column header of a leaf node, the hide column header button will be displayed. After clicking hide, a display button and a hidden prompt line will be displayed in the adjacent sibling cell, just click the mouse Expand, you can configure hiddenColumns to achieve默认隐藏and交互式隐藏. See details or specific examples

const s2DataConfig = {
  fields: {
    columns: ['fieldA', 'fieldB']
  }
}

const s2Options = {
  interaction: {
    // 默认隐藏
    hiddenColumns: ['fieldA']
  },
  // 关闭手动隐藏
  tooltip: {
    operation: {
      hiddenColumns: false
    }
  }
};

Row and column width and height adjustment

S2 provides three layout methods ( preview ) by default:列等宽布局``行列等宽布局and紧凑布局, and you can also drag and drop the row/column header to adjust dynamically

You can configure resize to control the width and height of the cells that need to be enabled to adjust the hot zone range, which is divided into three parts: corner header, row header, and column header. The default is to enable all of them. You can quickly turn on or off all resize by setting boolean type values, and you can also configure hotspots in each area to turn on or off by object type. View specific examples

const s2Options = {
  interaction: {
    resize: true
  },
};

// 等价于
// const s2Options = {
//   interaction: {
//     resize: {
//       rowCellVertical:true,
//       cornerCellHorizontal:true,
//       colCellHorizontal:true,
//       colCellVertical:true
//     }
//   },
// };

You can also configure resize.visible and resize.disable properties, which are used to control the display of the resize hotspot and customize the drag-and-drop verification logic respectively. View specific examples

Example: Cell width is not allowed to be reduced

const s2Options = {
  interaction: {
    resize: {
      disable: (resizeInfo) => resizeInfo.resizedWidth <= resizeInfo.width;
    }
  },
};

Example: Only the first 4 cells display the resize hotspot

const s2Options = {
  interaction: {
    resize: {
      enable: (cell) => {
        const meta = cell.getMeta();
        return meta.colIndex < 3
      }
    }
  },
};

Merge Cells

View details or specific examples

link jump

View details or specific examples

scroll

view details

reset interaction

Cases where reset interactions are supported:

• Click on non-table space
• Press Esc key
• Click again after selecting the cell

Corresponding event: GLOBAL_RESET

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

Configurable autoResetSheetStyle to turn off reset interaction. View specific examples

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

call the API

S2 has built-in some interaction-related API , which are uniformly mounted under the s2.interaction namespace. You can call them to achieve your effects after getting the SpreadSheet instance , such as选中所有单元格,获取列头单元格and other common methods , please refer to the Interaction instance class for details

const s2 = new PivotSheet()
s2.interaction.selectAll()

Interested in the principles behind the interaction implementation? Welcome to the article "Canvas Table Interaction You Don't Know"