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.
<!-- 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.
// 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.
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.
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.
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));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.
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.
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.
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.
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.
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.
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
}]
});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].
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.
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.
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).
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.
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.
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
}]
});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.
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.
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.
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.
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.
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' }
]
}]
});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.
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.
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.
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.
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.
// 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 }
}]
});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.
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.
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.
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.
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.
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] }]
}]
});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).
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.
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.
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.
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.
// 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 }
]
}]
});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.
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.
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.
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.
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.
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);
}
});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.
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.
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.
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.
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.
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 });
}
});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.
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.
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.
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.
// 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.
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);
}
});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.
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.
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.
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.
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.
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' }
}
]
});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.
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.
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.
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.
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.
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 }]
}]
});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).
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.
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.
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.
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.
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).
// 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' }
}
}
});
});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.
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.
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.
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.
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.
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' }
}]
});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.
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.
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.
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.
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.
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
});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.
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.
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'.
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.
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.
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
});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.
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.
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.
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.
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.
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] }
]
});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.
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.
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.
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.
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'.
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'
});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.
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.
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.
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.
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.
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
]
}
}]
});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.
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.
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.
// 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.
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.
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
}
]
}
});Snippets de ECharts relacionados
Copy-paste ready code for common tasks.
Bar Chart
Category bar chart with axis tooltip and styled bars.
Line Chart
Smooth multi-series line chart with area fill.
Pie Chart
Donut-style pie with emphasis effect and percentage labels.
Scatter Plot
Scatter plot with point size encoded by a third dimension.
Radar Chart
Radar with multiple indicators and overlaid value series.
Options & Series
Dataset-driven multi-series chart with grid and legend config.
Tooltip
Custom HTML tooltip with crosshair axis pointer.
Responsive
Resize chart on window and container changes, with cleanup.
Was this helpful?