Skip to content

ECharts Folha de referência

Poderosa biblioteca de gráficos e visualização da Apache.

01

Primeiros passos

Configuração e primeiro gráfico

O ECharts é inicializado num elemento DOM com width/height explícitos. setOption configura o gráfico inteiro. Apache ECharts (antes Baidu ECharts) é uma das bibliotecas de gráficos JS mais poderosas.

echarts
<!-- include ECharts -->
<script src="https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js"></script>

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

<script>
const chart = echarts.init(document.getElementById('chart'));
chart.setOption({
  title: { text: 'Sales' },
  xAxis: { data: ['Q1', 'Q2', 'Q3', 'Q4'] },
  yAxis: {},
  series: [{
    type: 'bar',
    data: [100, 200, 150, 300]
  }]
});
</script>

Init com tema e renderer

init recebe (dom, theme, opts). O renderer 'svg' é mais nítido em qualquer zoom e produz um DOM menor para gráficos simples, enquanto 'canvas' é mais rápido para datasets grandes. devicePixelRatio controla a nitidez em retina. Sempre chame dispose() ao remover um gráfico para liberar memória.

echarts
// register a theme (defined elsewhere or imported)
echarts.registerTheme('myTheme', {
  color: ['#5470c6', '#91cc75'],
  backgroundColor: '#f5f5f5'
});

// renderer: 'canvas' (default, faster) or 'svg' (sharper, lighter)
const chart = echarts.init(document.getElementById('chart'), 'myTheme', {
  renderer: 'svg',
  devicePixelRatio: 2,
  width: 800,
  height: 600,
  locale: 'EN'
});

// detached from DOM later
chart.dispose();

Redimensionamento responsivo

O ECharts não redimensiona sozinho quando o container muda — você precisa chamar chart.resize(). ResizeObserver é a forma moderna de observar o tamanho do container (melhor que window resize para mudanças de layout). Sempre dispose() na desmontagem para evitar vazamentos em SPAs.

echarts
const chart = echarts.init(document.getElementById('chart'));
chart.setOption({ /* ... */ });

// resize when window changes
window.addEventListener('resize', () => chart.resize());

// or observe the container
const ro = new ResizeObserver(() => chart.resize());
ro.observe(document.getElementById('chart'));

// resize with explicit size
chart.resize({ width: 500, height: 300, silent: false });

// cleanup
window.addEventListener('unload', () => chart.dispose());

Modos de mesclagem do setOption

Por padrão, setOption faz deep-merge das novas opções nas existentes, então você pode atualizar partes individuais. notMerge: true substitui a option inteira (útil quando a contagem de séries muda). replaceMerge mira tipos de componente específicos (series, xAxis) para substituição parcial. lazyUpdate agrupa múltiplas chamadas setOption numa única renderização.

echarts
const chart = echarts.init(document.getElementById('chart'));

// merge (default): deep-merges with existing option
chart.setOption({ xAxis: { data: ['A', 'B'] } });

// notMerge: replace entire option (old config discarded)
chart.setOption({ xAxis: { data: ['X', 'Y'] } }, { notMerge: true });

// replaceMerge: replace specific component types only
chart.setOption(
  { series: [{ type: 'bar', data: [5, 6] }] },
  { replaceMerge: ['series'] }
);

// lazyUpdate: batch updates, apply on next frame
chart.setOption({ series: [{ data: [1, 2] }] }, { lazyUpdate: true });

Ciclo de vida: getInstanceByDom e dispose

Chamar init num DOM que já tem um gráfico lança erro. Use getInstanceByDom para verificar. dispose() libera memória e remove o gráfico; o elemento DOM permanece. O atributo _echarts_instance_ marca os containers de gráfico — consulte-o para achar e limpar gráficos órfãos. Sempre faça dispose nos hooks de unmount do framework.

echarts
function mountChart(dom) {
  // avoid double-init on the same DOM node
  const existing = echarts.getInstanceByDom(dom);
  if (existing) return existing;

  const chart = echarts.init(dom);
  chart.setOption({ /* ... */ });
  return chart;
}

// in a framework cleanup (React useEffect / Vue onUnmounted):
function unmount(dom) {
  const chart = echarts.getInstanceByDom(dom);
  if (chart) chart.dispose();  // free memory + remove DOM
}

// dispose all charts on a page
echarts.disposeAll?.();  // not built-in; iterate manually
Array.from(document.querySelectorAll('[_echarts_instance_]'))
  .forEach(dom => echarts.dispose(dom));
02

Gráficos de barras

Barra básica

Um gráfico de barras precisa de um xAxis de categoria e um yAxis de valor. Cada valor de series.data mapeia a uma categoria. itemStyle controla a aparência das barras. Para barras verticais, o eixo de categoria é o x; para barras horizontais, troque os tipos dos eixos x e y.

echarts
chart.setOption({
  xAxis: {
    type: 'category',
    data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri']
  },
  yAxis: { type: 'value' },
  series: [{
    type: 'bar',
    data: [120, 200, 150, 80, 70],
    itemStyle: { color: '#5470c6' }
  }]
});

Barras agrupadas e empilhadas

Múltiplas séries de barra com o mesmo xAxis são agrupadas por padrão. Para empilhá-las, dê a cada série o mesmo nome de stack. Empilhar acumula os valores por categoria. Use stack: 'total' em todas as séries que devem empilhar juntas — séries sem nome de stack continuam agrupadas.

echarts
chart.setOption({
  xAxis: { type: 'category', data: ['Q1', 'Q2', 'Q3', 'Q4'] },
  yAxis: { type: 'value' },
  // GROUPED: multiple series render side by side
  series: [
    { type: 'bar', name: 'A', data: [10, 20, 30, 40] },
    { type: 'bar', name: 'B', data: [15, 25, 35, 45] }
  ]
});

// STACKED: add stack with same name to each series
chart.setOption({
  series: [
    { type: 'bar', name: 'A', stack: 'total', data: [10, 20, 30, 40] },
    { type: 'bar', name: 'B', stack: 'total', data: [15, 25, 35, 45] }
  ]
});

Barra horizontal

Uma barra horizontal é só um gráfico de barras com o eixo de categoria no yAxis e o de valor no xAxis. Labels com position: 'right' ficam no fim da barra. Barras horizontais são melhores para nomes de categoria longos ou ao comparar muitas categorias — evitam labels rotacionados.

echarts
chart.setOption({
  // swap: category axis becomes yAxis
  yAxis: {
    type: 'category',
    data: ['Apple', 'Banana', 'Cherry', 'Date']
  },
  xAxis: { type: 'value' },
  series: [{
    type: 'bar',
    data: [120, 200, 150, 80],
    label: {
      show: true,
      position: 'right'  // label at end of bar
    }
  }]
});

Barra com fundo e cantos arredondados

showBackground desenha uma trilha atrás de cada barra (estilo barra de progresso). itemStyle.borderRadius arredonda os cantos das barras — passe [topLeft, topRight, bottomRight, bottomLeft] para barras verticais; ordem inversa para horizontais. borderRadius pode ser um número (os cantos) ou um array.

echarts
chart.setOption({
  xAxis: { type: 'category', data: ['A', 'B', 'C', 'D'] },
  yAxis: { type: 'value' },
  series: [{
    type: 'bar',
    data: [50, 80, 60, 90],
    showBackground: true,
    backgroundStyle: {
      color: 'rgba(180, 180, 180, 0.2)',
      borderRadius: [4, 4, 0, 0]
    },
    itemStyle: {
      borderRadius: [8, 8, 0, 0]  // round top corners
    }
  }]
});

Corrida de barras (dinâmica)

Uma corrida de barras anima a reordenação. Ordene o array de dados, depois atualize tanto as categorias do yAxis quanto os dados das séries. animationDurationUpdate controla a suavidade da transição. yAxis.inverse: true coloca o maior valor no topo. É popular para histórias de dados animadas.

echarts
const data = [
  { name: 'A', value: 10 },
  { name: 'B', value: 20 }
];

chart.setOption({
  xAxis: { type: 'value', max: 100 },
  yAxis: { type: 'category', inverse: true },
  series: [{
    type: 'bar',
    data: data.map(d => ({ value: d.value, name: d.name })),
    label: { show: true, position: 'right' },
    // sort bars by value on each update
    animationDuration: 500,
    animationDurationUpdate: 500
  }]
});

// update data on interval
setInterval(() => {
  data.forEach(d => d.value += Math.random() * 10);
  data.sort((a, b) => b.value - a.value);
  chart.setOption({
    yAxis: { data: data.map(d => d.name) },
    series: [{ data: data.map(d => d.value) }]
  });
}, 1000);

Largura e espaçamento das barras

barWidth aceita pixels ou porcentagem da banda de categoria. barGap é o espaço entre barras dentro de um grupo (só importa com múltiplas séries). barCategoryGap é o espaço entre grupos. Porcentagens são relativas à banda de categoria, então permanecem proporcionais ao redimensionar.

echarts
chart.setOption({
  xAxis: { type: 'category', data: ['A', 'B', 'C', 'D'] },
  yAxis: { type: 'value' },
  series: [{
    type: 'bar',
    data: [50, 80, 60, 90],
    barWidth: '40%',          // width of each bar
    barGap: '20%',            // gap between bars in same group
    barCategoryGap: '40%',    // gap between category groups
    // fixed pixel width also works:
    // barWidth: 30
  }]
});
03

Gráficos de linha

Linha básica

Um gráfico de linha usa type: 'line'. Os pontos aparecem por padrão com marcadores de símbolo; defina symbol: 'none' para ocultá-los. A linha conecta os pontos na ordem dos dados. Para séries temporais, use type: 'time' no xAxis com pares [timestamp, value].

echarts
chart.setOption({
  xAxis: { type: 'category', data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'] },
  yAxis: { type: 'value' },
  series: [{
    type: 'line',
    data: [120, 200, 150, 80, 70],
    symbol: 'circle',      // point marker
    symbolSize: 8
  }]
});

Linha suave e área

smooth: true curva a linha (interpolação Catmull-Rom). areaStyle preenche a área sob a linha; um gradiente (stops de cor lineares) dá um visual esmaecido. boundaryGap: false no eixo de categoria faz a linha começar na borda do eixo y, em vez de deixar um espaço.

echarts
chart.setOption({
  xAxis: { type: 'category', boundaryGap: false, data: ['Mon','Tue','Wed','Thu','Fri'] },
  yAxis: { type: 'value' },
  series: [{
    type: 'line',
    data: [120, 200, 150, 80, 70],
    smooth: true,           // curved line
    areaStyle: {            // fill under line
      color: {
        type: 'linear',
        x: 0, y: 0, x2: 0, y2: 1,
        colorStops: [
          { offset: 0, color: 'rgba(84,112,198,0.5)' },
          { offset: 1, color: 'rgba(84,112,198,0.05)' }
        ]
      }
    }
  }]
});

Linha multi-série

Múltiplas séries renderizam como linhas separadas, distinguidas por cor. A legenda alterna a visibilidade. lineStyle.type aceita 'solid', 'dashed', 'dotted'. Cada série pode ter seu próprio estilo. O nome na legenda deve corresponder ao series.name.

echarts
chart.setOption({
  legend: { data: ['Email', 'Search'] },
  xAxis: { type: 'category', data: ['Mon','Tue','Wed','Thu','Fri'] },
  yAxis: { type: 'value' },
  series: [
    {
      type: 'line',
      name: 'Email',
      data: [120, 132, 101, 134, 90],
      lineStyle: { width: 3, type: 'solid' }
    },
    {
      type: 'line',
      name: 'Search',
      data: [220, 182, 191, 234, 290],
      lineStyle: { width: 2, type: 'dashed' }
    }
  ]
});

Área empilhada

Gráficos de área empilhada usam type: 'line' com o mesmo nome de stack e um areaStyle. Cada série empilha sobre a anterior. emphasis.focus: 'series' destaca a série inteira no hover. Útil para mostrar composição ao longo do tempo (por exemplo, tráfego por fonte).

echarts
chart.setOption({
  xAxis: { type: 'category', boundaryGap: false, data: ['Mon','Tue','Wed','Thu','Fri'] },
  yAxis: { type: 'value' },
  series: [
    {
      type: 'line',
      name: 'A',
      stack: 'total',
      areaStyle: {},
      data: [120, 132, 101, 134, 90],
      emphasis: { focus: 'series' }
    },
    {
      type: 'line',
      name: 'B',
      stack: 'total',
      areaStyle: {},
      data: [220, 182, 191, 234, 290]
    }
  ]
});

Linha em degraus

step transforma uma linha em escada. 'start' degrau antes do ponto, 'middle' (simétrico) no ponto, 'end' depois. Gráficos de degraus são ótimos para valores que mudam de forma discreta (níveis de estoque, status de servidor) em vez de contínua.

echarts
chart.setOption({
  xAxis: { type: 'category', data: ['Mon','Tue','Wed','Thu','Fri'] },
  yAxis: { type: 'value' },
  series: [{
    type: 'line',
    data: [120, 200, 150, 80, 70],
    step: 'middle',          // 'start' | 'middle' | 'end'
    symbol: 'none',
    lineStyle: { width: 2 }
  }]
});

Linha com eixo temporal

Com type: 'time', o eixo formata datas automaticamente e trata intervalos irregulares. Os pontos de dados são pares [timestamp, value]. O ECharts espaça os pontos pelo tempo real deles, então lacunas nos dados aparecem corretamente. É a escolha certa para séries temporais com intervalos variados.

echarts
chart.setOption({
  xAxis: { type: 'time' },   // auto-parses timestamps
  yAxis: { type: 'value' },
  series: [{
    type: 'line',
    data: [
      [new Date('2024-01-01').getTime(), 100],
      [new Date('2024-01-02').getTime(), 200],
      [new Date('2024-01-05').getTime(), 150],
      [new Date('2024-01-10').getTime(), 300]
    ],
    smooth: true
  }]
});
04

Gráficos de pizza

Pizza básica

Gráficos de pizza não usam eixos — series.data é um array de {value, name}. radius controla o tamanho da pizza como porcentagem da menor dimensão do container. Estilos emphasis aplicam no hover. A legenda deriva os labels automaticamente de data.name.

echarts
chart.setOption({
  series: [{
    type: 'pie',
    radius: '60%',          // radius of pie
    data: [
      { value: 1048, name: 'Search' },
      { value: 735, name: 'Direct' },
      { value: 580, name: 'Email' },
      { value: 484, name: 'Union' },
      { value: 300, name: 'Video' }
    ],
    emphasis: {
      itemStyle: {
        shadowBlur: 10,
        shadowOffsetX: 0,
        shadowColor: 'rgba(0,0,0,0.5)'
      }
    }
  }]
});

Rosca (anel)

Definir radius como [inner, outer] cria uma rosca. Um label central é um padrão comum (mostrar total ou um KPI). avoidLabelOverlap: false mantém os labels onde estão. O raio interno controla a espessura do anel — [50%, 70%] é um anel fino; [0%, 70%] é uma pizza completa.

echarts
chart.setOption({
  series: [{
    type: 'pie',
    radius: ['40%', '70%'],   // [inner, outer] = ring
    avoidLabelOverlap: false,
    label: {
      show: true,
      position: 'center',     // center label
      formatter: 'Total\n{c}'
    },
    data: [
      { value: 1048, name: 'A' },
      { value: 735, name: 'B' },
      { value: 580, name: 'C' }
    ]
  }]
});

Rosa (Nightingale)

roseType torna o raio da fatia proporcional ao valor (rosa de Nightingale). 'area' usa sqrt(value) para o raio (proporcional à área), 'radius' usa o valor diretamente. Cada fatia tem o mesmo ângulo, mas raios diferentes. Bom para comparar magnitudes em que julgar só pelo ângulo é difícil.

echarts
chart.setOption({
  series: [{
    type: 'pie',
    radius: ['10%', '70%'],
    roseType: 'area',         // or 'radius'
    data: [
      { value: 40, name: 'A' },
      { value: 38, name: 'B' },
      { value: 32, name: 'C' },
      { value: 30, name: 'D' },
      { value: 28, name: 'E' }
    ],
    label: { show: true }
  }]
});

Pizza com labels personalizados

label.formatter suporta variáveis de template: {a} (nome da série), {b} (nome do dado), {c} (valor), {d} (porcentagem). labelLine controla a linha conectora. length é o segmento perto da fatia, length2 o segmento perto do label. Labels personalizados tornam gráficos de pizza muito mais legíveis.

echarts
chart.setOption({
  series: [{
    type: 'pie',
    radius: '60%',
    label: {
      formatter: '{b}: {d}%',   // name: percentage
      color: '#333',
      fontSize: 14
    },
    labelLine: {
      show: true,
      length: 15,              // first segment
      length2: 20,             // second segment
      smooth: true
    },
    data: [
      { value: 1048, name: 'Search' },
      { value: 735, name: 'Direct' }
    ]
  }]
});

Pizza semicircular

Combinar startAngle e endAngle cria pizzas parciais (meia, quarto, estilo gauge). center posiciona a pizza — ['50%','70%'] a empurra para baixo, para que uma pizza de 180° fique na base. Pizzas parciais costumam ser usadas como gauges ou em dashboards estilizados.

echarts
chart.setOption({
  series: [{
    type: 'pie',
    radius: ['40%', '70%'],
    center: ['50%', '70%'],    // move down
    startAngle: 180,           // start at left
    endAngle: 360,             // end at right -> semicircle
    data: [
      { value: 60, name: 'A' },
      { value: 30, name: 'B' },
      { value: 10, name: 'C' }
    ]
  }]
});
05

Gráficos de dispersão

Dispersão básica

Gráficos de dispersão usam dois eixos de valor; cada ponto de dados é [x, y]. symbolSize controla o tamanho do ponto (fixo ou por ponto via função). A dispersão revela correlação entre duas variáveis. Ambos os eixos são type: 'value' (numéricos), diferente de barra/linha baseados em categoria.

echarts
chart.setOption({
  xAxis: { type: 'value' },
  yAxis: { type: 'value' },
  series: [{
    type: 'scatter',
    symbolSize: 12,
    data: [
      [10, 20], [15, 25], [20, 30], [25, 35],
      [30, 40], [35, 45], [40, 50], [45, 55]
    ],
    itemStyle: { color: '#5470c6' }
  }]
});

Gráfico de bolhas (tamanho por valor)

Um gráfico de bolhas é um scatter em que o tamanho do ponto codifica uma terceira dimensão. Passe [x, y, size] por ponto e defina symbolSize como uma função que retorna o tamanho. A função roda por ponto, então cada bolha escala independentemente. Útil para dados de 3 variáveis sem um gráfico 3D.

echarts
chart.setOption({
  xAxis: { type: 'value' },
  yAxis: { type: 'value' },
  series: [{
    type: 'scatter',
    // each point: [x, y, size]
    data: [
      [10, 20, 30],
      [15, 25, 60],
      [20, 30, 12],
      [25, 35, 45]
    ],
    symbolSize: function (data) {
      return data[2];           // use 3rd element as size
    }
  }]
});

Dispersão com visualMap (cor por valor)

visualMap mapeia uma dimensão de dados para cor. dimension: 2 colore pelo 3º elemento (índice 2) de cada ponto. inRange.color define o gradiente. Isso adiciona uma quarta dimensão (cor) a um scatter. O componente visualMap mostra a legenda com um slider.

echarts
chart.setOption({
  xAxis: { type: 'value' },
  yAxis: { type: 'value' },
  visualMap: {
    min: 0,
    max: 100,
    dimension: 2,             // map color to 3rd element
    inRange: { color: ['#50a3ba', '#eac736', '#d94e5d'] },
    right: 10,
    top: 'center'
  },
  series: [{
    type: 'scatter',
    data: [[10,20,30], [15,25,60], [20,30,12]],
    symbolSize: 15
  }]
});

Effect scatter (animado)

effectScatter adiciona uma animação de ondulação ao redor de cada ponto — ótimo para destacar pontos-chave (alertas, principais cidades). showEffectOn controla quando a ondulação toca. brushType: 'stroke' é mais leve; 'fill' é mais marcante. Use com moderação — ondulações demais distraem.

echarts
chart.setOption({
  xAxis: { type: 'value' },
  yAxis: { type: 'value' },
  series: [{
    type: 'effectScatter',    // animated ripple
    symbolSize: function (data) { return data[2]; },
    data: [[10, 20, 30], [15, 25, 60]],
    showEffectOn: 'render',   // 'render' or 'emphasis'
    rippleEffect: {
      brushType: 'stroke',    // 'stroke' or 'fill'
      period: 4,
      scale: 3
    }
  }]
});

Dispersão em larga escala

Para milhares de pontos, habilite a renderização progressiva — o ECharts divide os dados em blocos e os renderiza ao longo de frames para evitar travamento. large: true usa uma única chamada de desenho otimizada. Combine com symbolSize pequeno e opacidade para lidar com sobreposição de pontos. Isso mantém 50k+ pontos fluidos.

echarts
// for thousands of points, use progressive rendering
chart.setOption({
  xAxis: { type: 'value' },
  yAxis: { type: 'value' },
  series: [{
    type: 'scatter',
    data: largeDataArray,    // 50k+ points
    symbolSize: 3,
    progressive: 2000,        // chunk size for progressive render
    progressiveThreshold: 5000,  // enable above this count
    large: true,              // optimize for many points
    largeThreshold: 2000,
    itemStyle: { opacity: 0.6 }
  }]
});
06

Gráficos de radar

Radar básico

Gráficos de radar precisam de um array radar.indicator definindo cada eixo (name e max). Os dados da série são um array de valores correspondendo aos indicadores. Radar é ótimo para comparar múltiplos atributos de poucos itens (estatísticas de jogadores, comparação de produtos). max define a escala de cada eixo.

echarts
chart.setOption({
  radar: {
    indicator: [
      { name: 'Speed', max: 100 },
      { name: 'Power', max: 100 },
      { name: 'Range', max: 100 },
      { name: 'Comfort', max: 100 },
      { name: 'Price', max: 100 }
    ]
  },
  series: [{
    type: 'radar',
    data: [{ value: [85, 70, 90, 65, 80], name: 'Car A' }]
  }]
});

Radar multi-série

Múltiplas entradas de dados renderizam polígonos sobrepostos, ideal para comparação. Cada entrada precisa de um name único que corresponda à legenda. Séries demais (5+) tornam gráficos de radar ilegíveis — os polígonos se sobrepõem numa mancha. Fique com 2-4 itens por clareza.

echarts
chart.setOption({
  legend: { data: ['Car A', 'Car B'] },
  radar: {
    indicator: [
      { name: 'Speed', max: 100 },
      { name: 'Power', max: 100 },
      { name: 'Range', max: 100 }
    ]
  },
  series: [{
    type: 'radar',
    data: [
      { value: [85, 70, 90], name: 'Car A' },
      { value: [60, 95, 75], name: 'Car B' }
    ]
  }]
});

Radar com área

areaStyle preenche o polígono do radar com cor semitransparente, tornando a forma mais fácil de ler. lineStyle enfatiza o contorno. Mantenha a opacidade do areaStyle baixa (0.2-0.4) para que séries sobrepostas continuem visíveis. Símbolos marcam cada vértice.

echarts
chart.setOption({
  radar: {
    indicator: [
      { name: 'A', max: 100 },
      { name: 'B', max: 100 },
      { name: 'C', max: 100 }
    ]
  },
  series: [{
    type: 'radar',
    data: [{ value: [85, 70, 90], name: 'Score' }],
    areaStyle: { opacity: 0.3 },
    lineStyle: { width: 2 },
    symbol: 'circle',
    symbolSize: 6
  }]
});

Forma e eixos do radar

shape: 'polygon' (padrão) dá eixos angulares; 'circle' faz anéis suaves. splitNumber controla a densidade do grid. splitArea alterna cores para um efeito zebra. axisName estiliza os labels dos eixos. Essas opções controlam a estrutura visual do gráfico sem tocar nos dados.

echarts
chart.setOption({
  radar: {
    shape: 'polygon',          // 'polygon' or 'circle'
    radius: '65%',
    splitNumber: 5,            // grid ring count
    axisName: {
      color: '#333',
      fontSize: 12
    },
    splitLine: { lineStyle: { color: '#ccc' } },
    splitArea: {
      areaStyle: { color: ['#fafafa', '#fff'] }
    },
    indicator: [
      { name: 'Speed', max: 100 },
      { name: 'Power', max: 100 }
    ]
  },
  series: [{ type: 'radar', data: [{ value: [80, 70] }] }]
});

Raio polar do radar

radius: [inner, outer] cria um radar em formato de anel (como uma rosca). center posiciona o gráfico. min num indicador define onde o eixo começa — útil quando os valores são altos (evita um polígono minúsculo no centro). Ajuste o center para deixar espaço para os labels dos eixos.

echarts
chart.setOption({
  radar: {
    indicator: [
      { name: 'A', max: 100, min: 0 },   // min sets the inner bound
      { name: 'B', max: 100 },
      { name: 'C', max: 100 }
    ],
    radius: ['20%', '70%'],   // [inner, outer] for ring radar
    center: ['50%', '55%']
  },
  series: [{
    type: 'radar',
    data: [{ value: [60, 70, 80] }]
  }]
});
07

Mapas de calor

Heatmap cartesiano

Um heatmap cartesiano precisa de um visualMap para colorir as células. Os dados são [x, y, value]. label: { show: true } imprime valores nas células (bom só para grids pequenos). calculable: true adiciona uma alça de slider. Heatmaps revelam padrões de densidade (por exemplo, atividade por hora).

echarts
const hours = ['12a','1a','2a','3a','4a','5a','6a','7a','8a','9a','10a','11a'];
const days = ['Sat','Sun','Mon','Tue','Wed','Thu','Fri'];

// data: [x, y, value]
const data = [[0,0,5],[0,1,1],[1,0,8] /* ... */];

chart.setOption({
  tooltip: {},
  xAxis: { type: 'category', data: hours },
  yAxis: { type: 'category', data: days },
  visualMap: {
    min: 0, max: 10,
    calculable: true,
    orient: 'horizontal',
    left: 'center', bottom: '5%'
  },
  series: [{
    type: 'heatmap',
    data: data,
    label: { show: true }
  }]
});

Heatmap de calendário

Heatmaps de calendário mostram valores diários ao longo de um ano (gráfico de contribuições estilo GitHub). calendar.range define o ano ou intervalo de datas. Os pontos de dados são [dateString, value]. O gradiente do visualMap define os stops de cor. cellSize controla o tamanho do quadrado — 'auto' se ajusta ao container.

echarts
const data = [];
// generate one year of data
for (let i = 0; i < 365; i++) {
  const date = new Date(2024, 0, 1);
  date.setDate(date.getDate() + i);
  data.push([date.toISOString().slice(0,10), Math.floor(Math.random() * 100)]);
}

chart.setOption({
  tooltip: {},
  visualMap: {
    min: 0, max: 100,
    inRange: { color: ['#ebedf0', '#c6e48b', '#7bc96f', '#239a3b', '#196127'] }
  },
  calendar: {
    range: '2024',
    cellSize: ['auto', 13],
    yearLabel: { show: true }
  },
  series: [{ type: 'heatmap', data: data }]
});

Estilo dos itens do heatmap

itemStyle.borderColor e borderWidth criam um efeito de separador de grid (bordas brancas distinguem as células). borderRadius arredonda os cantos das células. Estilos emphasis aplicam no hover. Um visualMap oculto (show: false) continua dirigindo as cores sem mostrar a legenda.

echarts
chart.setOption({
  xAxis: { type: 'category', data: ['A','B','C','D'] },
  yAxis: { type: 'category', data: ['X','Y','Z'] },
  visualMap: { min: 0, max: 100, show: false },
  series: [{
    type: 'heatmap',
    data: [[0,0,80],[0,1,30],[1,0,50]],
    itemStyle: {
      borderColor: '#fff',       // white grid lines
      borderWidth: 2,
      borderRadius: 4
    },
    emphasis: {
      itemStyle: { shadowBlur: 10 }
    }
  }]
});

Heatmap punch card

Um punch card é um heatmap 7x24 mostrando atividade por dia da semana e hora. Cada célula é um intervalo de tempo. O itemStyle arredondado faz parecer pontos. Punch cards revelam padrões semanais (por exemplo, quando um servidor é mais movimentado). Os dados são um grid completo de 168 células.

echarts
const data = [];
for (let day = 0; day < 7; day++) {
  for (let hour = 0; hour < 24; hour++) {
    data.push([hour, day, Math.floor(Math.random() * 50) + 1]);
  }
}

chart.setOption({
  xAxis: { type: 'category', data: Array.from({length:24}, (_,i) => i + 'h') },
  yAxis: { type: 'category', data: ['Sun','Mon','Tue','Wed','Thu','Fri','Sat'] },
  visualMap: { max: 50, inRange: { color: ['#fff', '#5470c6'] } },
  series: [{
    type: 'heatmap',
    data: data,
    itemStyle: { borderRadius: 10, borderWidth: 2, borderColor: '#fff' }
  }]
});

Heatmap em mapa geográfico

Combinar geo com uma série map colore regiões por valor. O visualMap dirige a escala de cores. Você precisa registrar um mapa primeiro via echarts.registerMap('china', geoJson). roam: true habilita pan/zoom com o mouse. É assim que mapas coropléticos (cor por região) são construídos.

echarts
// requires a registered geo map (e.g. echarts.registerMap)
chart.setOption({
  geo: { map: 'china', roam: true },
  visualMap: {
    min: 0, max: 1000,
    inRange: { color: ['#e0ecf4', '#005824'] }
  },
  series: [{
    type: 'map',
    map: 'china',
    data: [
      { name: 'Beijing', value: 800 },
      { name: 'Shanghai', value: 950 }
    ]
  }]
});
08

Gráficos de árvore

Árvore básica (vertical)

Gráficos de árvore renderizam dados hierárquicos. layout: 'orthogonal' com orient: 'LR' faz uma árvore da esquerda para a direita. expandAndCollapse permite clicar para dobrar/desdobrar subárvores. leaves configura o estilo dos nós folha. Tree é perfeito para organogramas, árvores de arquivos e taxonomias.

echarts
const data = {
  name: 'Root',
  children: [
    {
      name: 'Child A',
      children: [{ name: 'A1' }, { name: 'A2' }]
    },
    {
      name: 'Child B',
      children: [{ name: 'B1' }]
    }
  ]
};

chart.setOption({
  series: [{
    type: 'tree',
    data: [data],
    top: '5%', left: '10%', bottom: '5%', right: '20%',
    layout: 'orthogonal',       // 'orthogonal' or 'radial'
    orient: 'LR',               // 'LR','RL','TB','BT'
    symbolSize: 10,
    label: { position: 'left' },
    leaves: { label: { position: 'right' } },
    expandAndCollapse: true,
    animationDuration: 550
  }]
});

Árvore horizontal

orient: 'LR' produz uma árvore horizontal (raiz à esquerda, folhas à direita). Os labels dos nós internos ficam à ESQUERDA do nó; os das folhas à DIREITA — isso evita sobreposição com os ramos. curveness no lineStyle cria conectores curvos para um visual mais suave.

echarts
chart.setOption({
  series: [{
    type: 'tree',
    data: [treeData],
    layout: 'orthogonal',
    orient: 'LR',              // left to right
    symbol: 'emptyCircle',
    symbolSize: 7,
    label: { position: 'left', verticalAlign: 'middle', align: 'right' },
    leaves: { label: { position: 'right', align: 'left' } },
    lineStyle: { color: '#999', width: 1, curveness: 0.5 }
  }]
});

Árvore radial

layout: 'radial' coloca a raiz no centro e irradia os filhos para fora em círculo. Funciona bem para árvores grandes, em que um layout horizontal seria largo demais. emphasis.focus: 'descendant' destaca os descendentes no hover, ajudando a rastrear ramos.

echarts
chart.setOption({
  series: [{
    type: 'tree',
    data: [treeData],
    layout: 'radial',          // circular layout
    symbol: 'circle',
    symbolSize: 8,
    label: {
      position: 'inside',
      rotate: 0
    },
    leaves: { label: { position: 'right' } },
    emphasis: { focus: 'descendant' },
    lineStyle: { curveness: 0.5 }
  }]
});

Árvore com símbolos personalizados

symbol e symbolSize aceitam funções para personalização por nó. Aqui, nós internos (com filhos) são retângulos maiores, enquanto folhas são círculos pequenos. Isso distingue visualmente os níveis da hierarquia. Combine com orient: 'TB' para um organograma clássico de cima para baixo.

echarts
const treeData = {
  name: 'CEO',
  value: 'Boss',
  children: [
    { name: 'VP Engineering', children: [{ name: 'Eng Lead' }] },
    { name: 'VP Sales', children: [{ name: 'Sales Lead' }] }
  ]
};

chart.setOption({
  series: [{
    type: 'tree',
    data: [treeData],
    symbol: function (params) {
      // custom symbol per node
      return params.data.children ? 'rect' : 'circle';
    },
    symbolSize: function (params) {
      return params.data.children ? 15 : 8;
    },
    orient: 'TB',
    label: { position: 'top', distance: 8 }
  }]
});

Controle de expandir/colapsar da árvore

initialTreeDepth controla quantos níveis ficam abertos inicialmente (null = sem limite, 0 = só a raiz). Clicar num nó com filhos alterna sua subárvore. O evento de clique permite reagir à seleção de nós — útil para UIs de drill-down. animationDurationUpdate suaviza expandir/colapsar.

echarts
chart.setOption({
  series: [{
    type: 'tree',
    data: [treeData],
    expandAndCollapse: true,
    initialTreeDepth: 2,        // expand first 2 levels
    collapse: 'collapseBtn',
    symbol: 'circle',
    animationDurationUpdate: 750
  }]
});

// programmatic control via API
chart.on('click', function (params) {
  if (params.componentType === 'series') {
    console.log('Node clicked:', params.data.name);
    console.log('Collapsed:', params.data.collapsed);
  }
});
09

Gráficos sunburst

Sunburst básico

Sunburst é uma árvore radial em que cada anel representa um nível da hierarquia. Interno = pai, externo = filhos. O valor de cada nó dirige seu tamanho angular. radius: [0, '90%'] faz um disco completo; [inner, outer] cria um sunburst em anel. Ótimo para visualizar proporções hierárquicas.

echarts
const data = [{
  name: 'Root',
  children: [
    {
      name: 'A',
      value: 15,
      children: [{ name: 'A1', value: 5 }, { name: 'A2', value: 10 }]
    },
    {
      name: 'B',
      value: 20,
      children: [{ name: 'B1', value: 20 }]
    }
  ]
}];

chart.setOption({
  series: [{
    type: 'sunburst',
    data: data,
    radius: [0, '90%'],
    label: { rotate: 'radial' }
  }]
});

Sunburst com levels

levels configura cada anel separadamente — a primeira entrada é a raiz, as seguintes mapeiam para níveis mais profundos. r0/r definem o raio interno/externo daquele nível. Rotações de label diferentes (radial, tangencial, 0) mantêm o texto legível em cada profundidade. Isso dá controle de estilização fino.

echarts
chart.setOption({
  series: [{
    type: 'sunburst',
    data: sunburstData,
    radius: ['15%', '90%'],
    levels: [
      {},  // root level (default)
      {
        r0: '15%',
        r: '45%',
        label: { rotate: 0, fontSize: 14 },
        itemStyle: { borderWidth: 2 }
      },
      {
        r0: '45%',
        r: '70%',
        label: { rotate: 'tangential', fontSize: 12 }
      },
      {
        r0: '70%',
        r: '90%',
        label: { rotate: 'radial', fontSize: 10 }
      }
    ]
  }]
});

Estilo e destaque do sunburst

emphasis.focus: 'ancestor' destaca o caminho do nó sob o cursor até a raiz — o usuário vê onde uma fatia se encaixa na hierarquia. borderWidth separa visualmente as fatias. Sunburst é interativo: clicar costuma aprofundar. Use o destaque de ancestral para manter o contexto em árvores profundas.

echarts
chart.setOption({
  series: [{
    type: 'sunburst',
    data: data,
    itemStyle: {
      borderColor: '#fff',
      borderWidth: 1
    },
    emphasis: {
      focus: 'ancestor'    // highlight ancestors on hover
    },
    highlight: {
      itemStyle: { color: '#ffb' }
    }
  }]
});

Sunburst com valor e ordenação

sort controla a ordenação das fatias dentro de um pai. nodeClick: 'zoomToNode' faz um clique dar zoom naquela subárvore (ótimo para explorar). minAngle oculta labels em fatias menores que 5 graus, evitando poluição. O valor dos nós pai é somado automaticamente dos filhos se omitido.

echarts
chart.setOption({
  series: [{
    type: 'sunburst',
    data: [{
      name: 'Root',
      children: [
        { name: 'A', value: 30, children: [/* ... */] },
        { name: 'B', value: 70, children: [/* ... */] }
      ]
    }],
    nodeClick: 'zoomToNode',   // click to zoom into subtree
    sort: 'desc',              // or 'asc', null
    label: { minAngle: 5 }     // hide labels on tiny slices
  }]
});

Drill-down do sunburst

Handlers de clique personalizados permitem construir sua própria UX de drill-down. Substitua os dados pelo nó clicado para dar zoom. Mantenha uma referência ao pai se quiser um botão 'voltar'. O drill-down do sunburst é excelente para explorar hierarquias profundas sem sobrecarregar a tela.

echarts
const data = [/* full tree */];
let currentRoot = data[0];

chart.setOption({
  series: [{
    type: 'sunburst',
    data: data,
    nodeClick: false
  }]
});

chart.on('click', function (params) {
  if (params.componentType === 'series' && params.data.children) {
    // manually drill down
    currentRoot = params.data;
    chart.setOption({
      series: [{ data: [currentRoot] }]
    }, { notMerge: true });
  }
});
10

Diagramas Sankey

Sankey básico

Sankey mostra fluxo entre nós. data são os nós (com nomes); links são os fluxos (source, target, value). A largura de cada link é proporcional ao valor. emphasis.focus: 'adjacency' destaca os nós conectados no hover. Ótimo para visualizar energia, dinheiro ou fluxo de usuários.

echarts
chart.setOption({
  series: [{
    type: 'sankey',
    data: [
      { name: 'Source A' },
      { name: 'Source B' },
      { name: 'Mid C' },
      { name: 'Sink D' }
    ],
    links: [
      { source: 'Source A', target: 'Mid C', value: 5 },
      { source: 'Source B', target: 'Mid C', value: 3 },
      { source: 'Mid C', target: 'Sink D', value: 8 }
    ],
    emphasis: { focus: 'adjacency' },
    lineStyle: { color: 'gradient', curveness: 0.5 }
  }]
});

Levels dos nós do Sankey

levels estiliza nós por profundidade (coluna). lineStyle.color: 'source' colore os links para casar com o nó de origem; 'target' com o destino; 'gradient' faz um degradê. nodeAlign posiciona os nós verticalmente dentro de uma coluna. Definir depth explicitamente força o posicionamento em coluna, sobrescrevendo o layout automático.

echarts
chart.setOption({
  series: [{
    type: 'sankey',
    data: [
      { name: 'A', depth: 0 },
      { name: 'B', depth: 1 },
      { name: 'C', depth: 2 }
    ],
    links: [
      { source: 'A', target: 'B', value: 10 },
      { source: 'B', target: 'C', value: 10 }
    ],
    levels: [
      { depth: 0, itemStyle: { color: '#fbb' }, lineStyle: { color: 'source' } },
      { depth: 1, itemStyle: { color: '#bfb' }, lineStyle: { color: 'target' } },
      { depth: 2, itemStyle: { color: '#bbf' } }
    ],
    nodeAlign: 'justify'      // 'left','right','justify'
  }]
});

Estilo e espaçamento dos nós do Sankey

nodeWidth define a espessura de cada retângulo de nó. nodeGap controla o espaçamento vertical. Espaços menores mostram mais nós, mas podem sobrepor. lineStyle.opacity torna os fluxos sutis para que os nós se destaquem. label.position: 'right' coloca os labels ao lado dos nós — comum para fluxos da esquerda para a direita.

echarts
chart.setOption({
  series: [{
    type: 'sankey',
    data: nodes,
    links: links,
    nodeWidth: 20,            // width of each node rectangle
    nodeGap: 10,              // vertical gap between nodes
    nodeAlign: 'justify',
    label: {
      fontSize: 12,
      color: '#333',
      position: 'right'
    },
    lineStyle: { opacity: 0.4 },
    itemStyle: { borderWidth: 0 }
  }]
});

Sankey com ciclo (dreno)

Ciclos verdadeiros fazem o Sankey do ECharts falhar. A alternativa é dividir um nó de recirculação em nós separados de 'entrada' e 'saída' (por exemplo, 'Recycle'), para que o fluxo seja acíclico. Isso representa visualmente loops de feedback. Sempre verifique a conservação do fluxo: o total de entrada de um nó deve igualar o total de saída.

echarts
// Sankey normally forbids cycles, but you can show feedback loops
// by splitting a node into two (in & out) with the same name suffix
chart.setOption({
  series: [{
    type: 'sankey',
    data: [
      { name: 'Input' },
      { name: 'Process' },
      { name: 'Output' },
      { name: 'Recycle' }
    ],
    links: [
      { source: 'Input', target: 'Process', value: 100 },
      { source: 'Process', target: 'Output', value: 80 },
      { source: 'Process', target: 'Recycle', value: 20 },
      { source: 'Recycle', target: 'Process', value: 20 }
    ],
    emphasis: { focus: 'adjacency' }
  }]
});

Interação do Sankey

Eventos de clique do Sankey distinguem nós de arestas via dataType. Use isso para construir painéis de detalhes mostrando especificidades do fluxo. label.formatter: '{b}: {c}' mostra nome e valor. O foco de adjacência destaca o caminho completo através de um nó sob o cursor, revelando cadeias de causa e efeito.

echarts
chart.setOption({
  series: [{
    type: 'sankey',
    data: nodes,
    links: links,
    emphasis: {
      focus: 'adjacency',
      lineStyle: { opacity: 0.8 }
    },
    label: { formatter: '{b}: {c}' },
    tooltip: { trigger: 'item' }
  }]
});

chart.on('click', function (params) {
  if (params.dataType === 'edge') {
    console.log('Flow from', params.data.source, 'to', params.data.target);
    console.log('Value:', params.data.value);
  } else if (params.dataType === 'node') {
    console.log('Node:', params.data.name);
  }
});
11

Gráficos de funil

Funil básico

Um funil mostra estágios de um processo em que cada estágio tem menos itens. sort: 'descending' (padrão) coloca o maior estágio no topo. Os dados devem estar ordenados pelo fluxo do processo. Funis são perfeitos para pipelines de vendas, análise de conversão e etapas de onboarding.

echarts
chart.setOption({
  series: [{
    type: 'funnel',
    data: [
      { value: 100, name: 'Visit' },
      { value: 75, name: 'Sign Up' },
      { value: 50, name: 'Trial' },
      { value: 25, name: 'Purchase' }
    ],
    sort: 'descending'      // 'descending','ascending','none'
  }]
});

Funil com sort e gap

sort: 'ascending' inverte o funil (menor no topo, como um gráfico de crescimento). gap separa as fatias para legibilidade. funnelAlign posiciona as fatias horizontalmente. minSize/maxSize limitam as larguras das fatias como porcentagens, garantindo que estágios minúsculos continuem visíveis.

echarts
chart.setOption({
  series: [{
    type: 'funnel',
    data: data,
    sort: 'ascending',          // smallest at top
    gap: 4,                     // pixel gap between slices
    funnelAlign: 'center',      // 'left','center','right'
    width: '60%',
    minSize: '20%',
    maxSize: '100%'
  }]
});

Labels do funil

position: 'inside' sobrepõe labels às fatias; 'left'/'right' os coloca fora, com linhas conectoras (labelLine). formatter: '{b}: {c}' mostra nome e valor. Use labels externos quando as fatias forem finas demais para texto interno. O emphasis amplia o label no hover.

echarts
chart.setOption({
  series: [{
    type: 'funnel',
    data: data,
    label: {
      show: true,
      position: 'inside',      // 'inside','left','right'
      formatter: '{b}: {c}'
    },
    labelLine: {
      show: true,
      length: 20,
      lineStyle: { width: 1, type: 'solid' }
    },
    emphasis: {
      label: { fontSize: 16 }
    }
  }]
});

Estilo dos itens do funil

itemStyle por fatia sobrescreve o ciclo padrão de cores. borderColor separa visualmente as fatias. Você também pode definir color em itens de dados individuais. Para um visual polido, use uma paleta sequencial (mais claro nas etapas iniciais, mais escuro nas convertidas) para reforçar a metáfora do funil.

echarts
chart.setOption({
  series: [{
    type: 'funnel',
    data: [
      { value: 100, name: 'A', itemStyle: { color: '#5470c6' } },
      { value: 75, name: 'B', itemStyle: { color: '#91cc75' } },
      { value: 50, name: 'C', itemStyle: { color: '#fac858' } }
    ],
    itemStyle: {
      borderColor: '#fff',
      borderWidth: 2,
      borderRadius: 0
    }
  }]
});

Funil comparativo

Múltiplas séries de funil podem ficar lado a lado para comparação de períodos. Dê a cada série seu próprio left/width para posicioná-las. Ótimo para visualizar testes A/B ou comparar conversão ano a ano. Use cores contrastantes por série para distingui-las.

echarts
chart.setOption({
  series: [
    {
      type: 'funnel',
      name: '2023',
      data: [{ value: 100, name: 'A' }, { value: 40, name: 'B' }],
      sort: 'descending',
      left: '5%', width: '40%',
      label: { position: 'inside' }
    },
    {
      type: 'funnel',
      name: '2024',
      data: [{ value: 120, name: 'A' }, { value: 60, name: 'B' }],
      sort: 'descending',
      left: '55%', width: '40%',
      label: { position: 'inside' }
    }
  ]
});
12

Gráficos gauge

Gauge básico

Um gauge mostra um único valor num arco. min/max definem a escala. progress mostra um arco colorido até o valor (com axisLine como trilha). detail renderiza o texto do valor no centro. valueAnimation transiciona o número suavemente. Ótimo para KPIs e dashboards de métrica única.

echarts
chart.setOption({
  series: [{
    type: 'gauge',
    min: 0,
    max: 100,
    progress: { show: true, width: 18 },
    axisLine: { lineStyle: { width: 18 } },
    detail: {
      valueAnimation: true,
      formatter: '{value}%'
    },
    data: [{ value: 70, name: 'Score' }]
  }]
});

Gauge com ponteiro

O estilo de ponteiro é o visual clássico de gauge. anchor é o pino central. Valores negativos de distance empurram ticks/labels para dentro (em direção ao centro). radius escala o gauge inteiro. Combine o ponteiro com splitLine para imitar um instrumento físico. Útil quando você quer uma sensação analógica.

echarts
chart.setOption({
  series: [{
    type: 'gauge',
    radius: '60%',
    min: 0, max: 100,
    pointer: { show: true, length: '60%', width: 5 },
    anchor: { show: true, size: 12, itemStyle: { color: '#333' } },
    axisTick: { distance: -15, length: 5 },
    splitLine: { distance: -20, length: 10 },
    axisLabel: { distance: -25 },
    data: [{ value: 42 }]
  }]
});

Gauge com faixas de cor

axisLine.lineStyle.color aceita um array de pares [limite, cor] para criar zonas coloridas (por exemplo, vermelho/amarelo/verde para níveis de risco). Os limites são frações (0-1). É a forma padrão de mostrar faixas 'seguro/aviso/perigo' num gauge. O ponteiro ou o arco de progresso indica o valor atual dentro dessas zonas.

echarts
chart.setOption({
  series: [{
    type: 'gauge',
    min: 0, max: 100,
    axisLine: {
      lineStyle: {
        width: 20,
        color: [
          [0.3, '#fd666d'],    // 0-30% red
          [0.7, '#37a2da'],    // 30-70% blue
          [1, '#91cc75']       // 70-100% green
        ]
      }
    },
    data: [{ value: 85 }]
  }]
});

Gauge multi-ponteiro

Múltiplas entradas de dados criam múltiplos ponteiros no mesmo gauge. Útil para comparar métricas relacionadas (CPU vs Memória vs Disco). Cada valor anima independentemente. Mantenha a contagem baixa (3-5 no máximo) ou o gauge fica poluído. Os nomes aparecem como labels perto de cada ponteiro.

echarts
chart.setOption({
  series: [{
    type: 'gauge',
    min: 0, max: 100,
    data: [
      { value: 60, name: 'CPU' },
      { value: 40, name: 'Memory' },
      { value: 80, name: 'Disk' }
    ],
    detail: { formatter: '{value}%' },
    title: { fontSize: 14 }
  }]
});

Gauge personalizado (progresso circular)

Definir startAngle/endAngle para abranger 360° cria um anel de progresso circular (como um anel do Apple Watch). Ocultar ponteiro/ticks/labels dá um visual minimalista limpo. roundCap arredonda as pontas do progresso. Esse estilo é popular em dashboards modernos — é um gauge disfarçado de anel.

echarts
chart.setOption({
  series: [{
    type: 'gauge',
    startAngle: 90,
    endAngle: -270,            // full circle
    pointer: { show: false },
    progress: {
      show: true,
      overlap: false,
      roundCap: true,
      clip: false
    },
    axisLine: { lineStyle: { width: 20, color: [[1, 'rgba(0,0,0,0.1)']] } },
    splitLine: { show: false },
    axisTick: { show: false },
    axisLabel: { show: false },
    detail: {
      valueAnimation: true,
      offsetCenter: ['0%', '0%'],
      fontSize: 30,
      formatter: '{value}%'
    },
    data: [{ value: 65 }]
  }]
});
13

Sistemas de coordenadas

Múltiplos eixos X

xAxis é um array — cada entrada é um eixo separado. As séries se vinculam a um eixo via xAxisIndex (base 0). Isso permite que um gráfico mostre duas métricas com escalas ou unidades diferentes. Use position para colocar eixos no topo/base. Comum em gráficos de ações (preço + volume) ou clima (temperatura + umidade).

echarts
chart.setOption({
  xAxis: [
    { type: 'category', data: ['A','B','C'], position: 'bottom' },
    { type: 'category', data: ['A','B','C'], position: 'top', axisLine: { onZero: false } }
  ],
  yAxis: { type: 'value' },
  series: [
    { type: 'line', data: [10, 20, 30], xAxisIndex: 0 },
    { type: 'line', data: [50, 60, 70], xAxisIndex: 1 }
  ]
});

Eixos Y duplos

Dois eixos y (esquerdo e direito) permitem traçar séries com unidades diferentes (por exemplo, receita em $ vs unidades vendidas). Cada série se vincula a um eixo via yAxisIndex. Codifique por cor a linha do eixo direito para casar com sua série, para que os usuários saibam qual linha lê contra qual eixo. Evite 3+ eixos — ficam confusos.

echarts
chart.setOption({
  xAxis: { type: 'category', data: ['Mon','Tue','Wed','Thu'] },
  yAxis: [
    { type: 'value', name: 'Sales', position: 'left' },
    { type: 'value', name: 'Orders', position: 'right', axisLine: { lineStyle: { color: '#ee6666' } } }
  ],
  series: [
    { type: 'bar', data: [200, 180, 250, 210], yAxisIndex: 0 },
    { type: 'line', data: [40, 35, 50, 42], yAxisIndex: 1, smooth: true }
  ]
});

Coordenadas polares

Coordenadas polares usam angleAxis (ao redor do círculo) e radiusAxis (do centro para fora). As séries definem coordinateSystem: 'polar'. startAngle: 90 coloca 0° no topo (norte). Polar é ótimo para dados direcionais (rosa dos ventos), padrões cíclicos ou variantes de rosa/nightingale.

echarts
chart.setOption({
  polar: {},
  angleAxis: {
    type: 'category',
    data: ['N','NE','E','SE','S','SW','W','NW'],
    startAngle: 90
  },
  radiusAxis: { type: 'value' },
  series: [{
    type: 'bar',
    data: [1, 2, 3, 4, 5, 6, 7, 8],
    coordinateSystem: 'polar'
  }]
});

Coordenadas de calendário

O sistema de coordenadas de calendário mapeia datas para células. Séries com coordinateSystem: 'calendar' se vinculam a ele. cellSize pode ser em pixels ou 'auto'. orient: 'horizontal' é o layout padrão de semanas em linha. dayLabel/monthLabel nameMap localiza os labels. Combine com heatmap para gráficos de contribuição.

echarts
chart.setOption({
  calendar: {
    range: ['2024-01-01', '2024-12-31'],
    cellSize: ['auto', 15],
    left: 50, right: 30,
    orient: 'horizontal',
    dayLabel: { nameMap: 'en' },
    monthLabel: { nameMap: 'en' },
    yearLabel: { show: false }
  },
  series: [{
    type: 'heatmap',
    coordinateSystem: 'calendar',
    data: calendarData
  }]
});

Coordenadas paralelas

Coordenadas paralelas traçam dados multidimensionais com um eixo por dimensão. Cada linha de dados vira uma polilinha cruzando os eixos. Isso revela correlações e agrupamentos em dados de alta dimensão (por exemplo, comparar carros por preço, consumo, ano, segurança). Útil para explorar dados.

echarts
chart.setOption({
  parallelAxis: [
    { dim: 0, name: 'Price' },
    { dim: 1, name: 'Mileage' },
    { dim: 2, name: 'Year' },
    { dim: 3, name: 'Safety', type: 'category', data: ['Low','Med','High'] }
  ],
  parallel: {
    parallelAxisDefault: {
      axisLine: { lineStyle: { color: '#999' } },
      nameTextStyle: { color: '#333' }
    }
  },
  series: [{
    type: 'parallel',
    data: [[20000, 30, 2020, 'High'], [25000, 25, 2021, 'Med']]
  }]
});

Configuração de mapa geográfico

registerMap vincula um GeoJSON a um nome para uso nas séries geo e map. roam habilita pan/zoom com o mouse. itemStyle.areaColor preenche as regiões; borderColor contorna. Estilos emphasis aplicam no hover. Geo sozinho mostra um mapa; pareie com uma série map para colorir regiões por valor (coropleto).

echarts
// load a map GeoJSON (must be registered before use)
fetch('https://geo.datav.aliyun.com/areas_v3/bound/100000_full.json')
  .then(r => r.json())
  .then(geoJson => {
    echarts.registerMap('china', geoJson);
    chart.setOption({
      geo: {
        map: 'china',
        roam: true,                  // pan & zoom
        zoom: 1.2,
        label: { show: false },
        itemStyle: {
          areaColor: '#eee',
          borderColor: '#fff'
        },
        emphasis: {
          label: { show: true },
          itemStyle: { areaColor: '#f5f5f5' }
        }
      }
    });
  });
14

Dataset

Dataset básico

Dataset separa os dados da configuração das séries. A fonte é um array 2D (linha de cabeçalho primeiro). seriesLayoutBy: 'column' faz cada série pegar uma coluna. encode mapeia colunas do dataset para x/y. Isso desacopla dados da apresentação — útil quando os dados são compartilhados entre vários gráficos.

echarts
chart.setOption({
  dataset: {
    source: [
      ['product', '2023', '2024'],
      ['Apple', 41, 56],
      ['Banana', 67, 28],
      ['Cherry', 89, 76]
    ]
  },
  xAxis: { type: 'category' },
  yAxis: {},
  series: [
    { type: 'bar', seriesLayoutBy: 'column', encode: { x: 'product', y: '2023' } },
    { type: 'bar', seriesLayoutBy: 'column', encode: { x: 'product', y: '2024' } }
  ]
});

Dataset com linhas de objetos

A fonte do dataset pode ser um array de objetos (linhas chave-valor). dimensions opcionalmente declara as colunas (útil quando linhas podem ter chaves ausentes). encode usa nomes de dimensão em vez de índices, para legibilidade. Linhas de objetos são mais fáceis de escrever à mão e mais autoexplicativas.

echarts
chart.setOption({
  dataset: {
    dimensions: ['product', 'count', 'score'],
    source: [
      { product: 'Apple', count: 41, score: 90 },
      { product: 'Banana', count: 67, score: 75 },
      { product: 'Cherry', count: 89, score: 88 }
    ]
  },
  xAxis: { type: 'category' },
  yAxis: {},
  series: [
    { type: 'bar', encode: { x: 'product', y: 'count' } },
    { type: 'bar', encode: { x: 'product', y: 'score' } }
  ]
});

Transforms de dataset (filter/sort)

Transforms encadeiam datasets: filter remove linhas, sort as ordena. Cada transform lê de fromDatasetId e expõe um novo dataset. As séries se vinculam via datasetId. Transforms permitem derivar visões de uma fonte sem copiar dados. Transforms suportados: filter, sort e personalizados via registerTransform.

echarts
chart.setOption({
  dataset: [
    {
      id: 'raw',
      source: [
        { product: 'A', sales: 100 },
        { product: 'B', sales: 50 },
        { product: 'C', sales: 200 }
      ]
    },
    {
      id: 'filtered',
      fromDatasetId: 'raw',
      transform: {
        type: 'filter',
        config: { and: [{ gte: { sales: 80 } }] }
      }
    },
    {
      id: 'sorted',
      fromDatasetId: 'filtered',
      transform: { type: 'sort', config: { order: 'desc', main: 'sales' } }
    }
  ],
  xAxis: { type: 'category' },
  yAxis: {},
  series: [{ type: 'bar', datasetId: 'sorted', encode: { x: 'product', y: 'sales' } }]
});

Encode e dimensions do dataset

encode mapeia colunas do dataset (por índice ou nome) para dimensões do gráfico. encode.tooltip lista as colunas a mostrar no tooltip. Aqui usamos as colunas 0/1 para posição, 2 para tamanho, 3 para cor (via itemStyle). A codificação torna o mesmo dataset reutilizável entre tipos de gráfico diferentes.

echarts
chart.setOption({
  dataset: {
    source: [
      [10, 20, 30, 'red'],
      [15, 25, 35, 'blue'],
      [20, 30, 40, 'green']
    ]
  },
  xAxis: { type: 'value' },
  yAxis: { type: 'value' },
  series: [{
    type: 'scatter',
    encode: {
      x: 0,                  // first column -> x
      y: 1,                  // second column -> y
      tooltip: [0, 1, 2]     // show these in tooltip
    },
    symbolSize: function (d) { return d[2]; }
  }]
});

Dataset com pizza

Gráficos de pizza precisam de mapeamentos itemName e value via encode. O mesmo dataset poderia alimentar um gráfico de barras (encode x:name, y:value) e um de pizza, com codificações diferentes. Essa é a força do dataset: uma fonte, múltiplas visões. Trocar o tipo de gráfico só muda o type da série e o encode.

echarts
chart.setOption({
  dataset: {
    source: [
      { name: 'Search', value: 1048 },
      { name: 'Direct', value: 735 },
      { name: 'Email', value: 580 }
    ]
  },
  series: [{
    type: 'pie',
    radius: '60%',
    encode: { itemName: 'name', value: 'value' }
  }]
});
15

VisualMap

VisualMap contínuo

VisualMap contínuo mapeia uma faixa numérica para cor (e opcionalmente tamanho). inRange.color é o gradiente (interpolado). calculable: true adiciona alças arrastáveis para filtrar. orient e left/top o posicionam. O visualMap dirige as cores das séries — você não define itemStyle.color manualmente.

echarts
chart.setOption({
  visualMap: {
    type: 'continuous',
    min: 0,
    max: 100,
    inRange: {
      color: ['#50a3ba', '#eac736', '#d94e5d'],
      symbolSize: [10, 50]
    },
    calculable: true,           // show slider handles
    orient: 'vertical',
    left: 'left', top: 'bottom'
  },
  series: [{
    type: 'scatter',
    data: [[10,20,30], [50,60,80], [80,90,95]]
  }]
});

VisualMap por faixas

VisualMap por faixas (piecewise) agrupa valores em intervalos discretos, cada um com sua cor. pieces define os intervalos (min/max/label/color). É mais claro que um gradiente quando você quer grupos categóricos (por exemplo, risco baixo/médio/alto). Útil para mapas coropléticos e scatter categorizado.

echarts
chart.setOption({
  visualMap: {
    type: 'piecewise',
    pieces: [
      { min: 0, max: 30, label: 'Low', color: '#91cc75' },
      { min: 30, max: 70, label: 'Mid', color: '#fac858' },
      { min: 70, max: 100, label: 'High', color: '#ee6666' }
    ],
    orient: 'horizontal',
    left: 'center', bottom: 10
  },
  series: [{
    type: 'scatter',
    data: data
  }]
});

VisualMap de categorias

VisualMap de categorias mapeia categorias em string para cores. categories lista os valores; inRange.color lista as cores correspondentes em ordem. dimension seleciona qual coluna de dados dirige o mapeamento (padrão 0). Ótimo quando seus dados têm um atributo categórico (por exemplo, prioridade, status) que você quer codificar por cor.

echarts
chart.setOption({
  visualMap: {
    type: 'piecewise',
    categories: ['Low', 'Medium', 'High'],
    inRange: { color: ['#91cc75', '#fac858', '#ee6666'] },
    dimension: 2                  // which data column to map
  },
  series: [{
    type: 'scatter',
    data: [
      [10, 20, 'Low'],
      [50, 60, 'Medium'],
      [80, 90, 'High']
    ]
  }]
});

VisualMap inline e fora da faixa

outOfRange estiliza pontos de dados fora da faixa selecionada do visualMap (por exemplo, esmaecidos quando filtrados). controller estiliza o próprio slider. Quando o usuário arrasta o slider para filtrar, os pontos fora da faixa desvanecem para outOfRange.color. Isso torna o visualMap um filtro interativo, não só uma legenda.

echarts
chart.setOption({
  visualMap: {
    min: 0, max: 100,
    inRange: { color: ['#5470c6', '#91cc75'] },
    outOfRange: { color: '#ccc', symbolSize: 5 },  // filtered out style
    controller: {
      inRange: { color: ['#5470c6', '#91cc75'] }
    },
    right: 10, top: 'center'
  },
  series: [{
    type: 'scatter',
    data: data
  }]
});

VisualMap em múltiplas séries

Por padrão, o visualMap afeta todas as séries. Use seriesIndex (número ou array) para mirar séries específicas. Isso permite codificar por cor uma série deixando as outras inalteradas — útil ao comparar um dataset destacado contra uma referência. Um único gráfico pode até ter múltiplos visualMaps para séries diferentes.

echarts
chart.setOption({
  visualMap: {
    min: 0, max: 100,
    inRange: { color: ['#5470c6', '#91cc75', '#fac858'] }
  },
  series: [
    { type: 'scatter', name: 'A', data: dataA },
    { type: 'scatter', name: 'B', data: dataB }
  ]
});

// bind visualMap to specific series only
chart.setOption({
  visualMap: { seriesIndex: 1 }   // only affects second series
});
16

Legenda

Legenda básica

A legenda lista os nomes das séries para alternar visibilidade. data deve corresponder a series.name (ou ser derivada automaticamente). icon estiliza o marcador. Clicar num item da legenda alterna sua série. A legenda se atualiza sozinha quando séries são adicionadas/removidas via setOption.

echarts
chart.setOption({
  legend: {
    data: ['Email', 'Search', 'Direct'],
    show: true,
    icon: 'roundRect',        // 'circle','rect','roundRect','triangle','diamond','pin','arrow'
    itemWidth: 20,
    itemHeight: 14,
    textStyle: { color: '#333', fontSize: 12 }
  },
  series: [
    { type: 'line', name: 'Email', data: [120, 200, 150] },
    { type: 'line', name: 'Search', data: [220, 180, 90] }
  ]
});

Posição e layout da legenda

orient e top/left posicionam a legenda. Layouts comuns: topo-centro (padrão), base-centro, vertical à direita. itemGap controla o espaçamento entre itens da legenda. Um fundo/borda sutil separa visualmente a legenda do gráfico. A posição importa — legendas na base liberam espaço vertical.

echarts
chart.setOption({
  legend: {
    orient: 'horizontal',          // 'horizontal' or 'vertical'
    top: 'top',                    // 'top','bottom','middle' or px
    left: 'center',                // 'left','center','right' or px
    itemGap: 20,                   // gap between items
    padding: 5,
    backgroundColor: '#f5f5f5',
    borderColor: '#ddd',
    borderWidth: 1,
    borderRadius: 4
  },
  series: [/* ... */]
});

Seleção e padrão da legenda

selected controla a visibilidade inicial. selectedMode: 'single' faz a legenda agir como botões de rádio (só uma série visível). O evento legendselectchanged dispara nas alternâncias do usuário — útil para persistir preferências ou sincronizar vários gráficos. O modo padrão é 'multiple'.

echarts
chart.setOption({
  legend: {
    selected: {
      'Email': true,        // visible by default
      'Search': false,      // hidden by default
      'Direct': true
    },
    selectedMode: 'multiple'   // 'single' or 'multiple'
  },
  series: [
    { type: 'line', name: 'Email', data: [120, 200, 150] },
    { type: 'line', name: 'Search', data: [220, 180, 90] },
    { type: 'line', name: 'Direct', data: [100, 90, 80] }
  ]
});

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

Legenda rolável

type: 'scroll' pagina a legenda quando há itens demais — botões de página aparecem. Essencial para gráficos com 10+ séries que, de outra forma, transbordariam. Estilos de ícone/texto de página personalizam a navegação. Legendas de rolagem vertical se encaixam bem na margem direita.

echarts
chart.setOption({
  legend: {
    type: 'scroll',           // 'plain' (default) or 'scroll'
    orient: 'vertical',
    right: 10, top: 20, bottom: 20,
    pageButtonItemStyle: { color: '#333' },
    pageIconColor: '#5470c6',
    pageIconInactiveColor: '#ccc',
    pageTextStyle: { color: '#333' },
    data: Array.from({length: 30}, (_, i) => 'Series ' + i)
  },
  series: [/* many series */]
});

Formatter da legenda e rich text

formatter personaliza os labels da legenda (por exemplo, maiúsculas, adicionar contagens). Rich text permite estilizar partes do label de forma diferente — defina estilos em textStyle.rich e referencie-os no formatter com a sintaxe {style|text}. Isso habilita legendas como 'A {count|42}' com estilização mista.

echarts
chart.setOption({
  legend: {
    data: ['A', 'B'],
    formatter: function (name) {
      return name.toUpperCase();
    },
    textStyle: {
      rich: {
        a: { color: '#5470c6', fontSize: 14, fontWeight: 'bold' },
        b: { color: '#91cc75', fontSize: 12 }
      }
    }
  },
  series: [/* ... */]
});

// legend can also show values via legendselectchanged + setOption
chart.on('legendselectchanged', () => {
  // dynamic label updates
});
17

Tooltip

Tooltip básico

trigger: 'item' mostra o tooltip por ponto de dados (scatter, pizza). 'axis' mostra para a categoria inteira (barra, linha). axisPointer desenha uma linha guia — 'shadow' é uma faixa translúcida (bom para barras), 'line' é uma linha fina (bom para gráficos de linha), 'cross' mostra linhas de x e y.

echarts
chart.setOption({
  tooltip: {
    trigger: 'axis',           // 'item','axis','none'
    show: true,
    backgroundColor: 'rgba(50,50,50,0.9)',
    borderColor: '#333',
    borderWidth: 1,
    padding: 10,
    textStyle: { color: '#fff', fontSize: 13 },
    axisPointer: { type: 'shadow' }   // 'line','shadow','cross'
  },
  xAxis: { type: 'category', data: ['A','B','C'] },
  yAxis: { type: 'value' },
  series: [{ type: 'bar', data: [10, 20, 30] }]
});

Formatter do tooltip

formatter personaliza o conteúdo do tooltip. Uma função recebe params (com name, value, seriesName, color, etc.) e retorna HTML. Templates de string usam {a} (nome da série), {b} (categoria/x), {c} (valor), {d} (porcentagem da pizza). Para tooltips de eixo multi-série, params é um array — itere-o.

echarts
chart.setOption({
  tooltip: {
    trigger: 'item',
    formatter: function (params) {
      // params has: name, value, seriesName, color, dataIndex, ...
      return '<b>' + params.name + '</b><br/>' +
             'Value: ' + params.value + '<br/>' +
             'Series: ' + params.seriesName;
    }
  },
  series: [{ type: 'pie', data: [/* ... */] }]
});

// string template form (for axis trigger)
chart.setOption({
  tooltip: {
    trigger: 'axis',
    formatter: '{a}: {b} = {c}'   // a=series, b=category, c=value
  }
});

Crosshairs do tooltip e axis pointer

O axisPointer.link de nível superior sincroniza ponteiros entre múltiplos gráficos (dashboards multi-gráfico) — passe xAxisIndex: 'all'. type: 'cross' mostra um crosshair completo com valores de x e y nos labels. crossStyle/lineStyle personalizam as linhas guia. Ponteiros sincronizados são essenciais para comparar dados em gráficos empilhados.

echarts
chart.setOption({
  tooltip: { trigger: 'axis' },
  xAxis: { type: 'category', data: ['Mon','Tue','Wed','Thu'] },
  yAxis: { type: 'value' },
  axisPointer: {
    link: [{ xAxisIndex: 'all' }],   // sync pointers across charts
    label: { backgroundColor: '#333' }
  },
  series: [{ type: 'line', data: [10, 20, 30, 40] }]
});

// per-axis pointer type
chart.setOption({
  tooltip: {
    axisPointer: {
      type: 'cross',
      crossStyle: { color: '#999' },
      lineStyle: { color: '#999', type: 'dashed' }
    }
  }
});

Tooltip com trigger item

trigger: 'item' mostra o tooltip ao passar o mouse sobre um único ponto de dados (fatia de pizza, ponto de scatter). É o padrão para pizza, scatter, radar. extraCssText adiciona CSS arbitrário (sombras, cantos arredondados) para estilização personalizada. percent está disponível para gráficos de pizza. Tooltips de item são precisos, por ponto.

echarts
chart.setOption({
  tooltip: {
    trigger: 'item',               // per-point, not per-axis
    formatter: function (p) {
      return p.name + ': ' + p.value + ' (' + p.percent + '%)';
    },
    backgroundColor: 'rgba(255,255,255,0.95)',
    borderColor: '#eee',
    textStyle: { color: '#333' },
    extraCssText: 'box-shadow: 0 2px 10px rgba(0,0,0,0.1);'
  },
  series: [{
    type: 'pie',
    data: [{ value: 60, name: 'A' }, { value: 40, name: 'B' }]
  }]
});

Tooltip com conteúdo rico

Para tooltips de eixo com múltiplas séries, params é um array. Itere-o para construir uma tabela HTML rica com marcadores de cor, valores e formatação. É assim que se constroem tooltips profissionais com alinhamento, totais ou unidades. Retornar HTML dá controle total de estilo via CSS inline.

echarts
chart.setOption({
  tooltip: {
    trigger: 'axis',
    axisPointer: { type: 'shadow' },
    formatter: function (params) {
      let html = '<div style="font-weight:bold;margin-bottom:4px;">'
        + params[0].name + '</div>';
      params.forEach(p => {
        html += '<div style="display:flex;align-items:center;">'
          + '<span style="display:inline-block;width:10px;height:10px;background:'
          + p.color + ';margin-right:6px;"></span>'
          + p.seriesName + ': ' + p.value
          + '</div>';
      });
      return html;
    }
  },
  series: [
    { type: 'bar', name: 'A', data: [10, 20, 30] },
    { type: 'bar', name: 'B', data: [15, 25, 35] }
  ]
});
18

Toolbox

Recursos do toolbox

O toolbox adiciona ícones de ação (no canto superior direito por padrão). dataZoom permite aos usuários arrastar e selecionar para dar zoom. dataView mostra os dados brutos (editáveis se readOnly: false). magicType troca o tipo de gráfico (linha/barra). restore reinicia. saveAsImage exporta PNG/SVG. Cada recurso tem sua própria config.

echarts
chart.setOption({
  toolbox: {
    show: true,
    right: 10, top: 10,
    feature: {
      dataZoom: { yAxisIndex: 'none' },
      dataView: { readOnly: false, title: 'Data', lang: ['Data','Close','Refresh'] },
      magicType: { type: ['line','bar','stack','tiled'] },
      restore: {},
      saveAsImage: { pixelRatio: 2, name: 'chart', type: 'png' }
    }
  },
  series: [{ type: 'bar', data: [10, 20, 30] }]
});

Data zoom via toolbox

O dataZoom do toolbox adiciona botões de 'zoom in/out' para seleção por arraste. Combine com componentes dataZoom: 'inside' (gestos de mouse/toque) e 'slider' (uma barra arrastável). yAxisIndex: 'none' restringe o zoom ao x. Para séries temporais com milhares de pontos, o dataZoom é essencial para navegar.

echarts
chart.setOption({
  toolbox: {
    feature: {
      dataZoom: {
        yAxisIndex: 'none',    // only zoom x axis
        title: { zoom: 'Zoom In', back: 'Zoom Out' }
      }
    }
  },
  dataZoom: [
    { type: 'inside', xAxisIndex: 0 },   // mouse wheel
    { type: 'slider', xAxisIndex: 0 }    // slider below chart
  ],
  xAxis: { type: 'category', data: longData },
  series: [{ type: 'line', data: longData }]
});

Data view (editar dados brutos)

dataView mostra os dados subjacentes do gráfico. readOnly: false permite aos usuários editar e re-renderizar. optionToContent/contentToOption permitem personalizar totalmente a visão (por exemplo, uma tabela HTML em vez de JSON). Útil para depurar ou deixar usuários avançados ajustarem dados. Edições disparam re-renderização.

echarts
chart.setOption({
  toolbox: {
    feature: {
      dataView: {
        readOnly: false,                  // editable
        title: 'View Data',
        lang: ['Data View', 'Close', 'Refresh'],
        optionToContent: function (opt) {
          // custom HTML rendering instead of JSON
          return '<div>Custom view</div>';
        },
        contentToOption: function (div) {
          // parse edited content back to option
          return opt;
        }
      }
    }
  }
});

Magic type e restore

magicType permite aos usuários alternar entre layouts linha/barra e empilhado/lado a lado em runtime — o ECharts cuida da conversão. restore reverte todas as mudanças do toolbox para a option original. O evento magicTypeChanged permite reagir a trocas de tipo (por exemplo, atualizar labels). Ótimo para explorar sem código extra.

echarts
chart.setOption({
  toolbox: {
    feature: {
      magicType: {
        type: ['line', 'bar', 'stack', 'tiled'],
        title: { line: 'Line', bar: 'Bar', stack: 'Stack', tiled: 'Tile' }
      },
      restore: { title: 'Restore' }
    }
  },
  series: [
    { type: 'bar', name: 'A', data: [10, 20, 30] },
    { type: 'bar', name: 'B', data: [15, 25, 35] }
  ]
});

chart.on('magicTypeChanged', function (params) {
  console.log('Switched to', params.currentType);
});

Salvar como imagem

saveAsImage exporta o gráfico como PNG/JPG. pixelRatio: 2 dobra a resolução para retina. excludeComponents remove elementos (como o toolbox) da exportação. getDataURL retorna uma string base64 para download ou upload programático. O renderer SVG exporta imagens vetoriais mais limpas quando o type é 'svg'.

echarts
chart.setOption({
  toolbox: {
    feature: {
      saveAsImage: {
        type: 'png',                  // 'png' or 'jpg'
        name: 'my-chart',
        pixelRatio: 2,                // higher = sharper
        backgroundColor: '#fff',
        excludeComponents: ['toolbox'],
        title: 'Download'
      }
    }
  }
});

// programmatic export
chart.getDataURL({
  type: 'png',
  pixelRatio: 2,
  backgroundColor: '#fff'
});
19

Marcas (MarkPoint / MarkLine / MarkArea)

MarkPoint (destacar pontos)

markPoint chama atenção para pontos específicos. Tipos embutidos: 'max', 'min', 'average'. Você também pode especificar coord: [x, y] para pontos personalizados. symbolSize escala o marcador. MarkPoints flutuam acima da série — não afetam a escala dos eixos. Útil para apontar extremos ou eventos.

echarts
chart.setOption({
  series: [{
    type: 'line',
    data: [10, 50, 30, 80, 20, 90],
    markPoint: {
      symbolSize: 50,
      data: [
        { type: 'max', name: 'Peak' },
        { type: 'min', name: 'Low' },
        { type: 'average', name: 'Avg' }
      ],
      label: { fontSize: 12 }
    }
  }]
});

MarkLine (linhas de referência)

markLine desenha linhas de referência. type: 'average' desenha uma linha horizontal na média. { yAxis: 60 } desenha uma linha horizontal personalizada (limiares, metas). { xAxis: 'Wed' } desenha uma linha vertical (marcadores de eventos). symbol: 'none' remove as setas das pontas para um visual mais limpo.

echarts
chart.setOption({
  series: [{
    type: 'bar',
    data: [10, 50, 30, 80, 20],
    markLine: {
      symbol: 'none',              // no end arrows
      lineStyle: { type: 'dashed', color: '#ee6666' },
      data: [
        { type: 'average', name: 'Avg' },
        { yAxis: 60, name: 'Threshold' },          // horizontal line at y=60
        { xAxis: 'Wed', name: 'Event' }            // vertical line at category
      ],
      label: { formatter: '{b}: {c}' }
    }
  }]
});

MarkArea (destacar regiões)

markArea sombreia uma região do gráfico. data é um array de pares [início, fim] — cada par define um retângulo por coord (valores de xAxis/yAxis). Útil para destacar horário comercial, fins de semana, recessões ou qualquer intervalo de interesse. silent: false faz reagir a eventos de hover.

echarts
chart.setOption({
  series: [{
    type: 'line',
    data: [10, 20, 30, 40, 50, 60, 70],
    markArea: {
      silent: false,
      itemStyle: { color: 'rgba(255, 200, 0, 0.2)' },
      data: [
        [
          { xAxis: 'Tue' },          // start
          { xAxis: 'Thu' }           // end
        ],
        [
          { xAxis: 'Fri' },
          { xAxis: 'Sat' }
        ]
      ],
      label: { show: true, position: 'top' }
    }
  }]
});

Marcas combinadas

Combine markPoint, markLine e markArea numa mesma série. Um gráfico de análise típico destaca o pico (markPoint), mostra a média e a meta (markLine) e sombreia um período notável (markArea). Cada marca tem estilização independente. Não exagere — marcas demais poluem o gráfico.

echarts
chart.setOption({
  series: [{
    type: 'line',
    data: [20, 50, 30, 80, 60, 90, 40],
    markPoint: {
      data: [{ type: 'max', name: 'Max' }]
    },
    markLine: {
      data: [
        { type: 'average', name: 'Average' },
        { yAxis: 70, name: 'Target', lineStyle: { color: '#91cc75' } }
      ]
    },
    markArea: {
      data: [[
        { xAxis: 'Wed' },
        { xAxis: 'Fri', itemStyle: { color: 'rgba(145,204,117,0.1)' } }
      ]]
    }
  }]
});

Marca com coordenadas personalizadas

Para posições personalizadas, use coord: [x, y] em vez dos tipos embutidos. markLine com coordenadas personalizadas recebe um array de dois objetos coord (início e fim) — você pode desenhar linhas arbitrárias (diagonais, linhas de tendência de uma regressão). symbol: 'pin' muda a forma do markPoint. Isso habilita anotações em pontos de dados específicos.

echarts
chart.setOption({
  series: [{
    type: 'scatter',
    data: [[10,20], [50,60], [80,90]],
    markPoint: {
      data: [
        { coord: [50, 60], name: 'Center', value: 'Origin' }
      ],
      symbol: 'pin',
      symbolSize: 40,
      itemStyle: { color: '#ee6666' }
    },
    markLine: {
      data: [
        [{ coord: [0, 0] }, { coord: [100, 100] }]  // diagonal line
      ]
    }
  }]
});
20

Animação e interação

Opções de animação

Controle a animação globalmente. animationDuration é o comprimento da animação de entrada. Nomes de easing incluem 'linear','cubicOut','elasticOut','bounceOut'. animationDelay como função escalona os itens (idx * 100 faz cada barra aparecer 100ms depois da anterior). Para datasets grandes, animationThreshold auto-desabilita a animação para manter o desempenho.

echarts
chart.setOption({
  animation: true,
  animationThreshold: 2000,        // disable above this data count
  animationDuration: 2000,         // entrance duration (ms)
  animationEasing: 'cubicOut',     // easing function
  animationDelay: function (idx) { // stagger by index
    return idx * 100;
  },
  animationDurationUpdate: 500,    // update transition
  animationEasingUpdate: 'cubicInOut',
  animationDelayUpdate: 0,
  series: [{ type: 'bar', data: [10, 20, 30, 40] }]
});

Funções de easing

O ECharts suporta 30+ funções de easing. 'cubicOut' (padrão) é uma desaceleração natural. 'elasticOut' e 'bounceOut' adicionam overshoot divertido. 'sinusoidalInOut' é suave e neutro. Para visualização de dados, prefira easings sutis (cubic, sinusoidal) — animações saltitantes distraem dos dados. Combine o easing com a personalidade da sua marca.

echarts
chart.setOption({
  animationEasing: 'elasticOut',
  // available easings:
  // linear, quadraticIn, quadraticOut, quadraticInOut,
  // cubicIn, cubicOut, cubicInOut,
  // quarticIn, quarticOut, quarticInOut,
  // quinticIn, quinticOut, quinticInOut,
  // sinusoidalIn, sinusoidalOut, sinusoidalInOut,
  // exponentialIn, exponentialOut, exponentialInOut,
  // circularIn, circularOut, circularInOut,
  // elasticIn, elasticOut, elasticInOut,
  // backIn, backOut, backInOut,
  // bounceIn, bounceOut, bounceInOut
  series: [{ type: 'bar', data: [10, 20, 30] }]
});

Animação de carregamento

showLoading exibe um overlay de spinner enquanto os dados são buscados. Chame hideLoading quando os dados estiverem prontos. Esse é o padrão padrão de dados assíncronos — mostrar carregamento, buscar, esconder carregamento, setOption. Personalize a cor do spinner e a mensagem para casar com sua app. A máscara impede interação do usuário durante o carregamento.

echarts
// show loading mask
chart.showLoading({
  text: 'Loading data...',
  color: '#5470c6',
  textColor: '#333',
  maskColor: 'rgba(255, 255, 255, 0.8)',
  zlevel: 0,
  fontSize: 14,
  showSpinner: true,
  spinnerRadius: 10,
  lineWidth: 2
});

// hide after data loads
fetch('/api/data').then(r => r.json()).then(data => {
  chart.hideLoading();
  chart.setOption({ series: [{ type: 'bar', data: data }] });
});

API de eventos

chart.on vincula handlers de eventos. Eventos comuns: click, dblclick, mouseover, legendselectchanged, datazoom, pieselectchanged. params carrega informações do componente. dispatchAction dispara ações (highlight, showTip, dataZoom) — útil para sincronizar UI externa com o gráfico ou mostrar tooltips programaticamente.

echarts
chart.on('click', function (params) {
  console.log('Clicked:', params.componentType, params.seriesType);
  console.log('Series:', params.seriesName, 'Data:', params.name, params.value);
  console.log(' dataIndex:', params.dataIndex);
});

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

chart.on('datazoom', function (params) {
  console.log('Zoom:', params.batch?.[0]?.start, params.batch?.[0]?.end);
});

// dispatch an action programmatically
chart.dispatchAction({
  type: 'highlight',
  seriesIndex: 0,
  dataIndex: 2
});

chart.dispatchAction({ type: 'showTip', x: 100, y: 100 });

Elementos gráficos (formas personalizadas)

graphic permite sobrepor formas personalizadas (texto, círculos, retângulos, imagens) ao gráfico — útil para marcas d'água, mensagens de estado vazio ou anotações. Elementos suportam posicionamento (left/top/right/bottom em px ou %), estilização e eventos. Renderizam acima ou abaixo do gráfico conforme o z. É a válvula de escape quando as opções padrão não bastam.

echarts
chart.setOption({
  graphic: {
    elements: [
      {
        type: 'text',
        left: 'center', top: 'middle',
        style: { text: 'No Data', fontSize: 24, fill: '#999' },
        invisible: false
      },
      {
        type: 'circle',
        shape: { cx: 50, cy: 50, r: 20 },
        style: { fill: '#5470c6' },
        onclick: function () { console.log('clicked'); }
      },
      {
        type: 'image',
        style: { image: 'logo.png', width: 100, height: 40 },
        left: 10, top: 10
      }
    ]
  }
});

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.