Aspose.Cells FOSS
Python
Guia do Desenvolvedor
Trabalhando com Gráficos

Trabalhando com Gráficos

Visão geral

Aspose.Cells FOSS uses a method-per-chart-type API. Instead of a generic add(ChartType.X, ...) chamada, cada tipo de gráfico tem seu próprio método dedicado em da planilha charts coleção:

MétodoTipo de gráfico
ws.charts.add_bar(top_row, left_col, bottom_row, right_col)Coluna agrupada (gráfico de barras)
ws.charts.add_line(top_row, left_col, bottom_row, right_col)Linha
ws.charts.add_pie(top_row, left_col, bottom_row, right_col)Pizza
ws.charts.add_area(top_row, left_col, bottom_row, right_col)Área

Todos os quatro parâmetros posicionais descrevem a área retangular na planilha onde o gráfico será incorporado. Os índices de linha e coluna são base zero. Cada método retorna um Chart objeto que você configura mais detalhadamente antes de salvar.

Limitação: Somente os tipos de gráfico LINE, BAR, PIE, AREA e STOCK podem ser salvos em XLSX. Chamando wb.save() com uma pasta de trabalho que contém qualquer outro tipo de gráfico (por exemplo, SCATTER, WATERFALL, RADAR, TREEMAP, HISTOGRAM) gerará NotImplementedError.

Adicionando um Gráfico de Colunas

O exemplo abaixo grava um pequeno conjunto de dados de receita por produto e, em seguida, adiciona um gráfico de colunas posicionado abaixo dos dados.

from aspose.cells_foss import Workbook, Cell

workbook = Workbook()
ws = workbook.worksheets[0]

##--- Data ---
ws.cells["A1"].value = "Product"
ws.cells["B1"].value = "Revenue"

products = ["Widget A", "Widget B", "Widget C", "Widget D", "Widget E"]
revenues = [12_500, 18_200, 9_800, 21_400, 15_600]

for i, (product, revenue) in enumerate(zip(products, revenues), start=2):
    ws.cells[f"A{i}"].value = product
    ws.cells[f"B{i}"].value = revenue

##--- Chart (rows 7–22, columns A–H, all zero-based) ---
##top_row=6, left_col=0, bottom_row=22, right_col=7
chart = ws.charts.add_bar(6, 0, 22, 7)

chart.title = "Revenue by Product"
chart.n_series.add("B2:B6", category_data="A2:A6", name="Revenue (USD)")
chart.show_legend = True
chart.legend_position = "bottom"

workbook.save("column_chart.xlsx")
print("Saved column_chart.xlsx")

Os dados ocupam as linhas 1–6 (linhas base zero 0–5), portanto top_row=6 coloca o gráfico imediatamente abaixo sem sobrepor os dados.

Adicionando um Gráfico de Linha

Gráficos de linha funcionam bem para mostrar tendências ao longo do tempo. A assinatura da chamada é idêntico a add_bar — apenas o nome do método muda.

from aspose.cells_foss import Workbook, Cell

workbook = Workbook()
ws = workbook.worksheets[0]

##--- Monthly trend data ---
ws.cells["A1"].value = "Month"
ws.cells["B1"].value = "Page Views"
ws.cells["C1"].value = "Conversions"

months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun"]
page_views   = [4_200, 5_100, 4_800, 6_300, 7_100, 6_800]
conversions  = [  210,   255,   230,   340,   390,   360]

for i, (month, pv, cv) in enumerate(zip(months, page_views, conversions), start=2):
    ws.cells[f"A{i}"].value = month
    ws.cells[f"B{i}"].value = pv
    ws.cells[f"C{i}"].value = cv

##--- Line chart below the data ---
chart = ws.charts.add_line(8, 0, 24, 8)

chart.title = "Monthly Website Metrics"
chart.n_series.add("B2:B7", category_data="A2:A7", name="Page Views")
chart.n_series.add("C2:C7", category_data="A2:A7", name="Conversions")
chart.show_legend = True
chart.legend_position = "bottom"

workbook.save("line_chart.xlsx")
print("Saved line_chart.xlsx")

Título do Gráfico e Legenda

Defina o título do gráfico atribuindo uma string simples diretamente a chart.title. O propriedade aceita um str — não tente acessar uma subpropriedade como .title.text, que não existe nesta biblioteca.

##Correct
chart.title = "Quarterly Sales"

##Wrong — raises AttributeError
##chart.title.text = "Quarterly Sales"

A visibilidade e a posição da legenda são controladas por duas propriedades:

chart.show_legend = True          # display the legend
chart.legend_position = "bottom"  # "bottom", "top", "left", "right"

Para ocultar a legenda completamente, defina chart.show_legend = False. O legend_position valor é ignorado quando a legenda está oculta.

Configuração de Séries de Dados

Use chart.n_series.add() para anexar intervalos de dados a um gráfico. Passe todos argumentos como argumentos nomeados para evitar confusão de ordem posicional:

chart.n_series.add("B2:B6", category_data="A2:A6", name="Revenue")

Você pode adicionar várias séries a um único gráfico chamando n_series.add mais do que uma vez. Cada chamada adiciona uma nova série:

from aspose.cells_foss import Workbook, Cell

workbook = Workbook()
ws = workbook.worksheets[0]

##Headers
ws.cells["A1"].value = "Quarter"
ws.cells["B1"].value = "North"
ws.cells["C1"].value = "South"
ws.cells["D1"].value = "East"

data = [
    ("Q1", 8_400, 6_100, 7_200),
    ("Q2", 9_200, 7_400, 8_100),
    ("Q3", 10_500, 8_900, 9_600),
    ("Q4", 11_800, 9_300, 10_200),
]

for i, row in enumerate(data, start=2):
    ws.cells[f"A{i}"].value = row[0]
    ws.cells[f"B{i}"].value = row[1]
    ws.cells[f"C{i}"].value = row[2]
    ws.cells[f"D{i}"].value = row[3]

chart = ws.charts.add_bar(6, 0, 22, 8)
chart.title = "Regional Sales by Quarter"

chart.n_series.add("B2:B5", category_data="A2:A5", name="North")
chart.n_series.add("C2:C5", category_data="A2:A5", name="South")
chart.n_series.add("D2:D5", category_data="A2:A5", name="East")

chart.show_legend = True
chart.legend_position = "bottom"

workbook.save("multi_series_chart.xlsx")
print("Saved multi_series_chart.xlsx")

Dados de Categoria

Os rótulos de categoria podem ser definidos no nível do gráfico ou no nível de cada série individual.

Dados de categoria ao nível do gráfico aplica-se a todas as séries como padrão:

chart.category_data = "A2:A5"

Dados de categoria ao nível da série (via o category_data argumento nomeado para n_series.add) substitui a configuração ao nível do gráfico para essa série específica:

chart.n_series.add("B2:B5", category_data="A2:A5", name="Revenue")

Quando todas as séries compartilham o mesmo intervalo de categorias, definir chart.category_data uma única vez é mais conciso. Quando as séries têm intervalos de categorias diferentes — por exemplo, dois conjuntos de dados com períodos de tempo diferentes — use o per-series keyword argument em vez disso.

Posicionamento do Gráfico

Os quatro parâmetros posicionais de cada add_* método definem um retângulo delimitador no planilha, medido em índices de linha e coluna baseados em zero:

add_bar(top_row, left_col, bottom_row, right_col)
ParâmetroSignificado
top_rowÍndice baseado em zero da primeira linha ocupada pelo gráfico
left_colÍndice baseado em zero da coluna mais à esquerda
bottom_rowÍndice baseado em zero da última linha ocupada pelo gráfico
right_colÍndice baseado em zero da coluna mais à direita

Um padrão comum é colocar o gráfico diretamente abaixo dos dados. Se seus dados terminam na linha 6 do Excel (índice de linha baseado em zero 5), inicie o gráfico em top_row=6:

from aspose.cells_foss import Workbook, Cell

workbook = Workbook()
ws = workbook.worksheets[0]

##Data in rows 1–5 (zero-based 0–4)
labels = ["Alpha", "Beta", "Gamma", "Delta", "Epsilon"]
values = [30, 45, 28, 60, 52]

ws.cells["A1"].value = "Category"
ws.cells["B1"].value = "Score"

for i, (label, val) in enumerate(zip(labels, values), start=2):
    ws.cells[f"A{i}"].value = label
    ws.cells[f"B{i}"].value = val

##Data ends at zero-based row 5 (Excel row 6).
##Place chart from row 6 to row 22, columns A–H (0–7).
chart = ws.charts.add_bar(6, 0, 22, 7)
chart.title = "Category Scores"
chart.n_series.add("B2:B6", category_data="A2:A6", name="Score")
chart.show_legend = False

workbook.save("positioned_chart.xlsx")
print("Saved positioned_chart.xlsx")

Faça o gráfico alto o suficiente para ser legível: uma altura de pelo menos 15 linhas (bottom_row - top_row >= 15) e uma largura de pelo menos 6 colunas é um ponto de partida razoável.

Erros Comuns

ErradoCorretoPor quê
ws.charts.add(ChartType.COLUMN, ...)ws.charts.add_bar(...)Não chame ws.charts.add(ChartType.X, ...) diretamente para tipos não suportados — ele gerará NotImplementedError para 11 de 16 tipos de gráfico. Use add_bar(), add_line(), add_pie(), add_area(), ou add_stock() em vez disso.
chart.title.text = "My Chart"chart.title = "My Chart"chart.title é uma propriedade de string simples, não um objeto com um .text sub‑propriedade.
chart.n_series.add("B2:B5", "A2:A5", "Revenue")chart.n_series.add("B2:B5", category_data="A2:A5", name="Revenue")Os segundo e terceiro parâmetros devem ser passados como argumentos nomeados para evitar ambiguidade.
chart = ws.charts.add_bar(0, 0, 15, 7) (sobrepõe dados)Coloque top_row abaixo da última linha de dadosUm gráfico que sobrepõe dados obscurece valores e causa layouts confusos.
chart.legend_position = "bottom" sem chart.show_legend = TrueConjunto chart.show_legend = True primeirolegend_position não tem efeito quando show_legend é False.

Veja Também

 Português