Initialize an ECharts instance

Initializing ECharts Instances

The ECharts instance is the starting point for data visualization using ECharts. Only after creating an instance can you set configuration options, bind data, and render charts. While the initialization process may seem simple, it involves several key details and configuration options.

Basic Initialization Method

The most common way to initialize is by creating an instance using the echarts.init() method. This method takes a DOM container as a parameter:

// Get the DOM element
const chartContainer = document.getElementById('chart-container');

// Initialize the ECharts instance
const myChart = echarts.init(chartContainer);

The DOM container must be predefined in the HTML and must have explicit width and height settings:

<div id="chart-container" style="width: 600px; height: 400px;"></div>

Detailed Initialization Parameters

The echarts.init() method can actually accept three parameters:

echarts.init(
  dom: HTMLDivElement|HTMLCanvasElement,
  theme?: string|Object,
  opts?: {
    devicePixelRatio?: number,
    renderer?: 'canvas'|'svg',
    width?: number|string,
    height?: number|string,
    locale?: string
  }
)

Theme Parameter

The second parameter specifies the theme, which can be a built-in theme name or a custom theme object:

// Use the built-in 'dark' theme
const chart = echarts.init(dom, 'dark');

// Use a custom theme
const customTheme = {
  color: ['#c23531','#2f4554','#61a0a8']
};
const chart = echarts.init(dom, customTheme);

Initialization Options

The third parameter, opts, includes several important configurations:

const chart = echarts.init(dom, null, {
  renderer: 'svg', // Use SVG renderer
  devicePixelRatio: 2, // Adaptation for high-resolution screens
  width: 'auto', // Automatic width
  height: 300 // Fixed height
});

Multiple Renderer Support

ECharts supports two rendering methods: Canvas and SVG. You can specify this during initialization:

// Force Canvas rendering
const canvasChart = echarts.init(dom, null, {renderer: 'canvas'});

// Force SVG rendering
const svgChart = echarts.init(dom, null, {renderer: 'svg'});

If not specified, ECharts will automatically choose the best rendering method based on browser capabilities and data volume.

Responsive Handling

After initialization, you typically need to handle browser window resizing:

const chart = echarts.init(dom);

window.addEventListener('resize', function() {
  chart.resize();
});

You can also set adaptive options during initialization:

const chart = echarts.init(dom, null, {
  width: '100%',
  height: '100%'
});

Multi-Instance Management

In complex applications, you may need to manage multiple ECharts instances:

const charts = {};

function initChart(domId) {
  const dom = document.getElementById(domId);
  charts[domId] = echarts.init(dom);
}

// Initialize multiple charts
initChart('chart1');
initChart('chart2');
initChart('chart3');

Error Handling

Add error handling logic during initialization:

try {
  const chart = echarts.init(dom);
} catch (error) {
  console.error('ECharts initialization failed:', error);
  // Display fallback content or error message
}

Advanced Initialization Scenarios

Delayed Initialization

For dynamically loaded DOM elements, initialize after the element is rendered:

new MutationObserver((mutations, observer) => {
  if (document.getElementById('dynamic-chart')) {
    const chart = echarts.init(document.getElementById('dynamic-chart'));
    observer.disconnect();
  }
}).observe(document.body, {childList: true, subtree: true});

Usage in Web Components

Initialize within components of frameworks like Vue:

// Vue example
export default {
  mounted() {
    this.initChart();
  },
  methods: {
    initChart() {
      this.chart = echarts.init(this.$refs.chartDom);
    }
  },
  beforeDestroy() {
    if (this.chart) {
      this.chart.dispose();
    }
  }
}

Performance Optimization Tips

For large data scenarios, pre-configure during initialization:

const chart = echarts.init(dom, null, {
  renderer: 'canvas',
  devicePixelRatio: 1,
  throttle: {
    throttleType: 'fixRate',
    throttleDelay: 500
  }
});

Server-Side Rendering (SSR) Considerations

Special handling is required for initialization in Node.js environments:

const { createCanvas } = require('canvas');
const echarts = require('echarts');

// Register canvas
echarts.setCanvasCreator(() => {
  return createCanvas(800, 600);
});

// Initialize
const chart = echarts.init(null, null, {
  ssr: true,
  width: 800,
  height: 600
});

Instance Method Extensions

After initialization, you can add custom methods by extending the prototype:

const chart = echarts.init(dom);

// Add a custom method
chart.constructor.prototype.myCustomMethod = function() {
  console.log('Custom method called');
};

Browser Compatibility Handling

Initialization strategy for older browsers:

function initECharts(dom) {
  if (typeof ResizeObserver === 'function') {
    // Modern browsers
    return echarts.init(dom);
  } else {
    // Compatibility mode
    const chart = echarts.init(dom);
    window.addEventListener('resize', () => chart.resize());
    return chart;
  }
}

Debugging Tips

During development, access instances via global variables for debugging:

const chart = echarts.init(dom);
window.__debug_chart = chart; // Convenient for console debugging

Memory Management

For long-running SPAs, ensure proper instance disposal:

// Initialize
const chart = echarts.init(dom);

// Dispose
chart.dispose();

Dynamic Theme Switching

Themes can be dynamically switched after initialization:

const chart = echarts.init(dom);

// Switch theme
function changeTheme(themeName) {
  echarts.dispose(dom);
  chart = echarts.init(dom, themeName);
}

Multilingual Support

Specify language during initialization:

// After loading the language pack
echarts.registerLocale('EN', {...});
const chart = echarts.init(dom, null, {
  locale: 'EN'
});

Special Environment Adaptation

Initialization in special environments like WeChat Mini Programs:

// Mini Program example
const chart = echarts.init(canvas, null, {
  width: 300,
  height: 200,
  devicePixelRatio: wx.getSystemInfoSync().pixelRatio
});