Methods for implementing custom charts

Methods for Implementing Custom Charts

ECharts provides a rich variety of chart types, but sometimes it is necessary to create fully custom charts based on business requirements. By understanding ECharts' core rendering mechanism, developers can break through the limitations of built-in charts and achieve highly customized data visualization effects.

Basics of Custom Series

Using the custom series type is the primary way to implement custom charts. After setting the type to 'custom' in the series configuration, the renderItem function must be defined to specify the drawing logic for graphic elements:

option = {
  series: [{
    type: 'custom',
    renderItem: function(params, api) {
      // Define graphic elements here
      return {
        type: 'rect',
        shape: {
          x: api.value(0),
          y: api.value(1),
          width: 20,
          height: api.value(2)
        },
        style: {
          fill: '#1890FF'
        }
      };
    },
    data: [[10, 20, 30], [50, 60, 40], [80, 30, 50]]
  }]
};

The renderItem function accepts two parameters:

• params: Contains information about the current rendering context.
• api: Provides methods for data access and coordinate transformation.

Types of Graphic Elements

ECharts supports various basic graphic elements that can be combined in renderItem:

Basic Shapes

return {
  type: 'circle',
  shape: {
    cx: api.value(0),
    cy: api.value(1),
    r: api.value(2)
  },
  style: {
    fill: '#FF6B81',
    stroke: '#FF4757'
  }
};

Composite Shapes

return {
  type: 'group',
  children: [{
    type: 'rect',
    shape: { /*...*/ },
    style: { /*...*/ }
  }, {
    type: 'text',
    style: {
      text: 'Label',
      x: 100,
      y: 100
    }
  }]
};

SVG Paths

return {
  type: 'path',
  shape: {
    path: 'M10,10 L50,50 L10,50 Z',
    layout: 'cover'
  },
  style: {
    fill: '#7BED9F'
  }
};

Data Mapping and Coordinate Transformation

The api object provides various data transformation methods:

// Get data value
const value = api.value(2); 

// Convert to pixel coordinates
const point = api.coord([api.value(0), api.value(1)]);

// Data range transformation
const size = api.size([2, 4], [1, 3]);

Example: Implementing a Bubble Chart Effect

renderItem: function(params, api) {
  const coord = api.coord([api.value(0), api.value(1)]);
  const size = api.size([0, 0], [api.value(2), api.value(2)]);
  
  return {
    type: 'circle',
    shape: {
      cx: coord[0],
      cy: coord[1],
      r: size[0] / 2
    },
    style: {
      fill: api.visual('color')
    }
  };
}

Animation and Interaction

Custom series support full animation and interaction:

return {
  type: 'rect',
  shape: { /*...*/ },
  style: { /*...*/ },
  // Animation configuration
  transition: ['shape'],
  animationDuration: 1000,
  // Interaction states
  emphasis: {
    style: {
      shadowBlur: 10,
      shadowColor: 'rgba(0,0,0,0.5)'
    }
  }
};

Performance Optimization Tips

Consider performance when handling large datasets:

1. Use Incremental Rendering

series: [{
  progressive: 1000,
  progressiveThreshold: 3000
}]

2. Simplify Graphic Elements

// Use simpler shapes instead of complex paths
type: 'rect' instead of type: 'path'

3. Enable GPU Acceleration

series: [{
  large: true,
  largeThreshold: 500
}]

Practical Example: Custom Dashboard

Implementing a circular dashboard with a pointer:

function renderMeter(params, api) {
  const angle = (api.value(0) / 100) * Math.PI * 1.8 - Math.PI * 0.9;
  const center = api.coord([api.value(1), api.value(2)]);
  const radius = api.size([0, 0], [api.value(3), api.value(3)])[0];
  
  return {
    type: 'group',
    children: [{
      // Dashboard background
      type: 'arc',
      shape: {
        cx: center[0],
        cy: center[1],
        r: radius,
        startAngle: -Math.PI * 0.9,
        endAngle: Math.PI * 0.9
      },
      style: {
        fill: '#EEE',
        stroke: '#DDD'
      }
    }, {
      // Pointer
      type: 'line',
      shape: {
        x1: center[0],
        y1: center[1],
        x2: center[0] + Math.cos(angle) * radius * 0.9,
        y2: center[1] + Math.sin(angle) * radius * 0.9
      },
      style: {
        stroke: '#FF4D4F',
        lineWidth: 3
      }
    }]
  };
}

option = {
  series: [{
    type: 'custom',
    renderItem: renderMeter,
    data: [[75, 50, 50, 30]]  // [value, x, y, radius]
  }]
};

Extending Custom Rendering

For more complex requirements, you can extend ECharts' renderer:

// Register custom shape type
echarts.graphic.registerShape('myShape', {
  buildPath: function(ctx, shape) {
    ctx.moveTo(shape.x, shape.y);
    // Custom drawing logic
    ctx.bezierCurveTo(/*...*/);
  }
});

// Use in renderItem
return {
  type: 'myShape',
  shape: {
    x: 100,
    y: 100
    // Custom properties
  }
};

Combining with Other Charts

Custom series can be mixed with standard charts:

option = {
  series: [
    // Standard line chart
    {
      type: 'line',
      data: [/*...*/]
    },
    // Custom markers
    {
      type: 'custom',
      renderItem: function() {
        return {
          type: 'image',
          style: {
            image: 'pin.png',
            x: 100,
            y: 200,
            width: 20,
            height: 30
          }
        };
      }
    }
  ]
};

Responsive Design

Ensure custom charts adapt to different sizes:

renderItem: function(params, api) {
  const containerWidth = api.getWidth();
  const containerHeight = api.getHeight();
  
  // Dynamically calculate element size based on container dimensions
  const elementSize = Math.min(containerWidth, containerHeight) * 0.1;
  
  return {
    type: 'circle',
    shape: {
      r: elementSize
      // ...
    }
  };
}

Debugging Tips

Use these debugging methods when developing custom charts:

1. Display Coordinate System Guidelines

// Add in renderItem
return {
  type: 'group',
  children: [
    // Custom graphics...
    {
      type: 'line',
      shape: {
        x1: 0, y1: 0,
        x2: api.getWidth(), y2: 0
      },
      style: {
        stroke: 'red',
        lineWidth: 1
      }
    }
  ]
};

2. Output Debugging Information

console.log('Data value:', api.value(0));
console.log('Coord:', api.coord([api.value(0), api.value(1)]));

3. Use ECharts Debugging Tools

// Enable in option
option = {
  tooltip: {
    formatter: function(params) {
      return JSON.stringify(params, null, 2);
    }
  }
};