or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

chart-management.mdchart-types.mdcomponents.mddata-operations.mdexport-rendering.mdextensions-customization.mdindex.mdinteraction-events.mdtheming-styling.mdutility-namespaces.md
tile.json

interaction-events.mddocs/

Interaction & Events

ECharts provides a comprehensive event system for handling user interactions, programmatic actions, and custom behaviors. This includes mouse events, touch events, chart actions, and custom event handling.

Capabilities

Event Handling

Register and manage event listeners for user interactions and chart events.

interface EChartsType {
  /**
   * Register event handler
   * @param eventName - Event name (e.g., 'click', 'mouseover')
   * @param handler - Event handler function
   * @param context - Context object for handler (optional)
   */
  on(eventName: string, handler: EventHandler, context?: any): void;
  
  /**
   * Register event handler with query condition
   * @param eventName - Event name
   * @param query - Query condition to filter events
   * @param handler - Event handler function
   * @param context - Context object for handler (optional)
   */
  on(eventName: string, query: EventQuery, handler: EventHandler, context?: any): void;
  
  /**
   * Unregister event handler
   * @param eventName - Event name
   * @param handler - Specific handler to remove (optional, removes all if not specified)
   */
  off(eventName: string, handler?: Function): void;
  
  /**
   * Trigger event programmatically
   * @param eventName - Event name
   * @param params - Event parameters
   */
  trigger(eventName: string, params?: any): void;
}

interface EventHandler {
  (params: EventParams): void;
}

interface EventQuery {
  seriesIndex?: number;
  seriesName?: string;
  dataIndex?: number;
  dataType?: string;
  name?: string;
  [key: string]: any;
}

interface EventParams {
  componentType: string;
  seriesType?: string;
  seriesIndex?: number;
  seriesName?: string;
  name?: string;
  dataIndex?: number;
  data?: any;
  dataType?: string;
  value?: any;
  color?: string;
  percent?: number;
  $vars?: string[];
  event?: Event;
  [key: string]: any;
}

Usage Examples:

// Basic event handling
chart.on('click', function(params) {
  console.log('Clicked:', params.name, params.value);
});

// Event handling with query condition
chart.on('mouseover', { seriesType: 'bar' }, function(params) {
  console.log('Hovered over bar:', params.data);
});

// Multiple event types
chart.on('click', handleClick);
chart.on('dblclick', handleDoubleClick);
chart.on('mouseover', handleMouseOver);
chart.on('mouseout', handleMouseOut);

// Remove event handler
chart.off('click', handleClick);

// Remove all handlers for an event
chart.off('click');

Mouse Events

Handle various mouse interactions including clicks, hovers, and selections.

// Available mouse events
type MouseEventName = 
  | 'click'
  | 'dblclick'
  | 'mousedown'
  | 'mousemove'
  | 'mouseup'
  | 'mouseover'
  | 'mouseout'
  | 'globalout'
  | 'contextmenu';

interface MouseEventParams extends EventParams {
  event: MouseEvent;
  offsetX: number;
  offsetY: number;
  clientX: number;
  clientY: number;
  pixelX: number;
  pixelY: number;
  topTarget: any;
  target: any;
}

Usage Example:

chart.on('click', function(params: MouseEventParams) {
  if (params.componentType === 'series') {
    console.log('Series clicked:', {
      seriesName: params.seriesName,
      dataIndex: params.dataIndex,
      value: params.value,
      position: [params.offsetX, params.offsetY]
    });
  }
});

Selection Events

Handle data selection, highlighting, and focus events for interactive data exploration.

// Selection event names
type SelectionEventName =
  | 'highlight'
  | 'downplay'
  | 'selectchanged'
  | 'legendselectchanged'
  | 'legendselected'
  | 'legendunselected'
  | 'pieselect'
  | 'pieunselect';

interface SelectionEventParams extends EventParams {
  type: string;
  selected?: { [key: string]: boolean };
  isSelected?: boolean;
  fromAction?: boolean;
  fromActionPayload?: any;
}

Usage Example:

// Handle selection changes
chart.on('selectchanged', function(params) {
  console.log('Selection changed:', params.selected);
  
  // Update UI based on selection
  updateSelectionUI(params.selected);
});

// Handle legend interactions
chart.on('legendselectchanged', function(params) {
  console.log('Legend selection:', params.name, params.selected);
});

Chart Actions

Programmatically trigger chart actions and handle their responses.

interface EChartsType {
  /**
   * Dispatch action to chart
   * @param payload - Action configuration
   * @param silent - Whether to suppress events (default: false)
   */
  dispatchAction(payload: ActionPayload, silent?: boolean): void;
}

interface ActionPayload {
  type: string;
  [key: string]: any;
}

// Common action types
interface HighlightAction extends ActionPayload {
  type: 'highlight';
  seriesIndex?: number;
  seriesName?: string;
  dataIndex?: number;
  name?: string;
}

interface DownplayAction extends ActionPayload {
  type: 'downplay';
  seriesIndex?: number;
  seriesName?: string;
  dataIndex?: number;
  name?: string;
}

interface SelectAction extends ActionPayload {
  type: 'select';
  seriesIndex?: number;
  seriesName?: string;
  dataIndex?: number;
  name?: string;
}

interface DataZoomAction extends ActionPayload {
  type: 'dataZoom';
  dataZoomIndex?: number;
  start?: number;
  end?: number;
  startValue?: number | string;
  endValue?: number | string;
}

interface ShowTooltipAction extends ActionPayload {
  type: 'showTip';
  seriesIndex?: number;
  dataIndex?: number;
  name?: string;
  position?: number[] | string;
  x?: number;
  y?: number;
}

Usage Examples:

// Highlight specific data point
chart.dispatchAction({
  type: 'highlight',
  seriesIndex: 0,
  dataIndex: 2
});

// Show tooltip programmatically
chart.dispatchAction({
  type: 'showTip',
  seriesIndex: 0,
  dataIndex: 1,
  position: [100, 200]
});

// Zoom to specific data range
chart.dispatchAction({
  type: 'dataZoom',
  start: 20,
  end: 80
});

// Select multiple data points
chart.dispatchAction({
  type: 'select',
  seriesIndex: 0,
  dataIndex: [1, 3, 5]
});

Brush Events

Handle data brushing and selection events for data filtering and analysis.

// Brush event names
type BrushEventName = 
  | 'brush'
  | 'brushEnd'
  | 'brushselected'
  | 'globalcursortaken';

interface BrushEventParams extends EventParams {
  areas: BrushArea[];
  command: 'select' | 'clear';
  batch?: BrushBatch[];
}

interface BrushArea {
  brushType: 'rect' | 'polygon' | 'lineX' | 'lineY';
  coordRange: number[][];
  range: number[][];
  panelId: string;
}

interface BrushBatch {
  seriesId: string;
  seriesIndex: number;
  seriesName: string;
  selected: {
    dataIndex: number[];
    data: any[];
  }[];
}

Usage Example:

chart.on('brushselected', function(params) {
  if (params.batch && params.batch.length > 0) {
    params.batch.forEach(batch => {
      console.log('Brushed series:', batch.seriesName);
      console.log('Selected data:', batch.selected);
    });
  }
});

Custom Events

Create and handle custom events for application-specific interactions.

// Custom event handling
interface CustomEventParams {
  type: string;
  detail?: any;
  [key: string]: any;
}

// Trigger custom events
chart.trigger('myCustomEvent', {
  detail: { customData: 'value' },
  timestamp: Date.now()
});

// Handle custom events
chart.on('myCustomEvent', function(params: CustomEventParams) {
  console.log('Custom event:', params.detail);
});

Event Delegation

Use event delegation patterns for efficient event handling with dynamic content.

// Event delegation using query conditions
chart.on('click', { dataType: 'node' }, function(params) {
  // Only handle clicks on nodes
  handleNodeClick(params);
});

chart.on('click', { seriesType: 'bar' }, function(params) {
  // Only handle clicks on bar charts
  handleBarClick(params);
});

// Component-specific event handling
chart.on('click', { componentType: 'legend' }, function(params) {
  // Handle legend clicks
  handleLegendClick(params);
});

Coordinate System Events

Handle events specific to different coordinate systems and components.

// Axis pointer events
chart.on('updateAxisPointer', function(params) {
  console.log('Axis pointer updated:', params.axesInfo);
});

// Data zoom events
chart.on('datazoom', function(params) {
  console.log('Data zoom changed:', {
    start: params.start,
    end: params.end,
    dataZoomId: params.dataZoomId
  });
});

// Timeline events (for timeline component)
chart.on('timelinechanged', function(params) {
  console.log('Timeline changed:', params.currentIndex);
});

// Map events
chart.on('geoselectchanged', function(params) {
  console.log('Geo selection changed:', params.selected);
});

Event Performance

Optimize event handling for better performance with large datasets.

// Throttle events for performance
let throttleTimer: number;
chart.on('mousemove', function(params) {
  if (throttleTimer) clearTimeout(throttleTimer);
  throttleTimer = setTimeout(() => {
    handleMouseMove(params);
  }, 16); // ~60fps
});

// Use event delegation to reduce handlers
chart.on('click', function(params) {
  switch (params.componentType) {
    case 'series':
      handleSeriesClick(params);
      break;
    case 'legend':
      handleLegendClick(params);
      break;
    case 'toolbox':
      handleToolboxClick(params);
      break;
  }
});

// Silent actions to prevent event cascades
chart.dispatchAction({
  type: 'highlight',
  dataIndex: 0
}, true); // silent = true

Types

interface Payload {
  type: string;
  [key: string]: any;
}

interface ECElementEvent {
  type: string;
  event: Event;
  target: any;
  topTarget: any;
  cancelBubble: boolean;
  offsetX: number;
  offsetY: number;
  gestureEvent: string;
  pinchX: number;
  pinchY: number;
  pinchScale: number;
  wheelDelta: number;
  zrX: number;
  zrY: number;
  which: number;
  stop: () => void;
}

interface HighlightPayload extends Payload {
  type: 'highlight';
  seriesIndex?: number;
  seriesName?: string;
  dataIndex?: number;
  name?: string;
}

interface DownplayPayload extends Payload {
  type: 'downplay';
  seriesIndex?: number;
  seriesName?: string;
  dataIndex?: number;
  name?: string;
}

interface SelectChangedPayload extends Payload {
  type: 'selectchanged';
  fromAction: boolean;
  fromActionPayload: any;
  selected: { [key: string]: number[] };
}