Interactive event handling

ECharts provides rich interactive capabilities, allowing users to engage with charts in various ways. Event handling for interactions is one of ECharts' core features. Developers can listen to these events and execute custom logic to achieve dynamic data updates, highlight displays, tooltip control, and other effects.

Event Types and Binding Methods

Interactive events in ECharts are mainly divided into two categories: mouse events and component events. Mouse events include basic interactions like clicks, hovers, and drags, while component events are related to specific chart components, such as legend toggling or data range zooming.

The basic syntax for binding events is as follows:

myChart.on('eventName', function(params) {
  // Event handling logic
});

Common mouse events include:

• 'click': Chart click event
• 'dblclick': Double-click event
• 'mousedown': Mouse press event
• 'mouseup': Mouse release event
• 'mouseover': Mouse hover event
• 'mouseout': Mouse leave event
• 'globalout': Mouse leave chart area event

Basic Event Handling Example

Below is a complete example of a click event handler. When a user clicks a bar in a bar chart, relevant information is output to the console:

// Initialize the chart
const chart = echarts.init(document.getElementById('main'));

// Configuration options
const option = {
  xAxis: {
    type: 'category',
    data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
  },
  yAxis: {
    type: 'value'
  },
  series: [{
    data: [120, 200, 150, 80, 70, 110, 130],
    type: 'bar'
  }]
};

// Set the configuration options
chart.setOption(option);

// Bind the click event
chart.on('click', function(params) {
  console.log('Click event parameters:', params);
  console.log('Data name:', params.name);
  console.log('Data value:', params.value);
  console.log('Series name:', params.seriesName);
});

Advanced Event Handling Techniques

1. Deep Dive into Event Parameters

The params parameter in the event callback function contains rich information, and its structure varies depending on the event type. For data item events, the typical structure is as follows:

{
  componentType: 'series', // Component type
  seriesType: 'bar',      // Series type
  seriesIndex: 0,         // Series index
  name: 'Tue',            // Data name
  dataIndex: 1,           // Data index
  data: 200,              // Raw data
  value: 200,             // Numerical value
  event: event            // Original event object
}

2. Conditional Event Handling

Implement conditional logic based on event parameters:

chart.on('click', function(params) {
  if (params.seriesType === 'bar') {
    // Bar chart-specific handling
    highlightBar(params.dataIndex);
  } else if (params.seriesType === 'line') {
    // Line chart-specific handling
    showTooltip(params.dataIndex);
  }
});

3. Event Debouncing

For high-frequency events (e.g., mouse movement), use debouncing to optimize performance:

function debounce(func, wait) {
  let timeout;
  return function() {
    clearTimeout(timeout);
    timeout = setTimeout(func, wait);
  };
}

chart.on('mousemove', debounce(function(params) {
  // Handling logic
}, 100));

Component-Specific Event Handling

1. Legend Events

The legend component provides various interactive events:

chart.on('legendselectchanged', function(params) {
  console.log('Legend selection changed:', params.selected);
});

chart.on('legendselected', function(params) {
  console.log('Legend selected:', params.name);
});

chart.on('legendunselected', function(params) {
  console.log('Legend unselected:', params.name);
});

2. Data Zoom Events

Handling events for the data zoom component:

chart.on('datazoom', function(params) {
  console.log('Zoom range:', params.start, params.end);
  console.log('Batch:', params.batch);
});

3. Timeline Events

Handling events for the timeline component:

chart.on('timelinechanged', function(params) {
  console.log('Timeline changed:', params.currentIndex);
});

Custom Interaction Implementation

1. Highlight Linking Effect

Implement linked highlighting across multiple charts:

// Chart 1
chart1.on('mouseover', function(params) {
  chart2.dispatchAction({
    type: 'highlight',
    seriesIndex: params.seriesIndex,
    dataIndex: params.dataIndex
  });
});

// Chart 2
chart2.on('mouseover', function(params) {
  chart1.dispatchAction({
    type: 'highlight',
    seriesIndex: params.seriesIndex,
    dataIndex: params.dataIndex
  });
});

2. Dynamic Data Updates

Trigger data updates via click events:

chart.on('click', function(params) {
  const newData = generateNewData(params.dataIndex);
  chart.setOption({
    series: [{
      data: newData
    }]
  });
});

3. Complex Interaction Combinations

Combine multiple actions for complex interactions:

chart.on('click', function(params) {
  // Show tooltip
  chart.dispatchAction({
    type: 'showTip',
    seriesIndex: params.seriesIndex,
    dataIndex: params.dataIndex
  });
  
  // Highlight current item
  chart.dispatchAction({
    type: 'highlight',
    seriesIndex: params.seriesIndex,
    dataIndex: params.dataIndex
  });
  
  // Cancel other highlights
  chart.dispatchAction({
    type: 'downplay',
    seriesIndex: params.seriesIndex,
    dataIndex: params.dataIndex
  });
});

Performance Optimization and Considerations

1. Event Unbinding

Unbind events when they are no longer needed:

// Bind event
const handler = function(params) {
  console.log(params);
};
chart.on('click', handler);

// Unbind specific event handler
chart.off('click', handler);

// Unbind all click events
chart.off('click');

2. Event Delegation

For large datasets, use event delegation to improve performance:

chart.on('click', {seriesIndex: 0}, function(params) {
  // Only handle events for the first series
});

3. Avoid Excessive Rendering

When updating charts in event handlers, merge option updates:

// Not recommended - triggers multiple renders
chart.on('click', function() {
  chart.setOption({...}, true); // Force update
});

// Recommended - merge updates
let pendingUpdate = null;
chart.on('click', function() {
  if (!pendingUpdate) {
    setTimeout(() => {
      chart.setOption(pendingUpdate);
      pendingUpdate = null;
    }, 100);
  }
  pendingUpdate = {...};
});

Mobile Adaptation

1. Touch Event Support

ECharts automatically maps mouse events to touch events, but differences should be noted:

chart.on('click', function(params) {
  // Responds to touch events on mobile
});

// Specifically handle touch events
chart.getZr().on('touchstart', function(params) {
  // Handle touch start
});

2. Gesture Recognition

Implement custom gesture interactions:

let startX, startY;
chart.getZr().on('touchstart', function(e) {
  startX = e.offsetX;
  startY = e.offsetY;
});

chart.getZr().on('touchend', function(e) {
  const deltaX = e.offsetX - startX;
  const deltaY = e.offsetY - startY;
  
  if (Math.abs(deltaX) > 50 && Math.abs(deltaY) < 30) {
    // Recognized as horizontal swipe
    handleSwipe(deltaX > 0 ? 'right' : 'left');
  }
});

Debugging and Troubleshooting

1. Event Logging

Comprehensive event logging aids debugging:

chart.on('click', function(params) {
  console.group('Click event details');
  console.log('Basic parameters:', params);
  console.log('Event object:', params.event);
  console.log('Chart instance:', this);
  console.groupEnd();
});

2. Common Issues and Solutions

Possible reasons for events not triggering and their solutions:

1. Chart not initialized correctly

// Ensure the DOM element exists and the chart is initialized
if (!chart.isDisposed()) {
  chart.on('click', handler);
}

2. Data items not interactive

// Check if series configuration has interactive settings
series: [{
  silent: false, // Must be false for interactivity
  // ...
}]

3. Event bubbling blocked

// Check if event bubbling is prevented on container elements
document.getElementById('main').addEventListener('click', function(e) {
  e.stopPropagation(); // This prevents ECharts from receiving the event
});