Aspose.Cells FOSS
Python
Guía del desarrollador
Trabajando con gráficos

Trabajando con gráficos

Visión general

Aspose.Cells FOSS utiliza una API de método por tipo de gráfico. En lugar de una llamada genérica add(ChartType.X, ...), cada tipo de gráfico tiene su propio método dedicado en la colección charts de la hoja de cálculo:

MétodoTipo de gráfico
ws.charts.add_bar(top_row, left_col, bottom_row, right_col)Columna agrupada (gráfico de barras)
ws.charts.add_line(top_row, left_col, bottom_row, right_col)Línea
ws.charts.add_pie(top_row, left_col, bottom_row, right_col)Circular
ws.charts.add_area(top_row, left_col, bottom_row, right_col)Área

Los cuatro parámetros posicionales describen el área rectangular en la hoja donde se incrustará el gráfico. Los índices de fila y columna son basados en cero. Cada método devuelve un objeto Chart que configuras más adelante antes de guardarlo.

Limitación: Solo los tipos de gráfico LINE, BAR, PIE, AREA y STOCK pueden guardarse en XLSX. Llamar a wb.save() con un libro de trabajo que contenga cualquier otro tipo de gráfico (p. ej., SCATTER, WATERFALL, RADAR, TREEMAP, HISTOGRAM) generará NotImplementedError.

Agregar un gráfico de columnas

El ejemplo a continuación escribe un pequeño conjunto de datos de ingresos por producto y luego agrega un gráfico de columnas ubicado debajo de los datos.

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")

Los datos ocupan las filas 1–6 (filas basadas en cero 0–5), por lo que top_row=6 coloca el gráfico inmediatamente debajo sin superponer los datos.

Añadiendo un gráfico de líneas

Los gráficos de líneas funcionan bien para mostrar tendencias a lo largo del tiempo. La firma de llamada es idéntica a add_bar — solo cambia el nombre del método.

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 del gráfico y leyenda

Establezca el título del gráfico asignando una cadena simple directamente a chart.title. La propiedad acepta un str — no intente acceder a una subpropiedad como .title.text, que no existe en esta biblioteca.

##Correct
chart.title = "Quarterly Sales"

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

La visibilidad y posición de la leyenda se controlan mediante dos propiedades:

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

Para ocultar la leyenda por completo, establezca chart.show_legend = False. El valor legend_position se ignora cuando la leyenda está oculta.

Configuración de series de datos

Use chart.n_series.add() para adjuntar rangos de datos a un gráfico. Pase todos los argumentos como keyword arguments para evitar confusión por orden posicional:

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

Puedes agregar varias series a un solo gráfico llamando a n_series.add más de una vez. Cada llamada agrega una nueva serie:

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")

Datos de la categoría

Las etiquetas de categoría pueden configurarse a nivel del gráfico o a nivel de la serie individual.

Datos de categoría a nivel de gráfico se aplican a todas las series por defecto:

chart.category_data = "A2:A5"

Datos de categoría a nivel de serie (a través del argumento de palabra clave category_data para n_series.add) sobrescribe la configuración a nivel de gráfico para esa serie específica:

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

Cuando todas las series comparten el mismo rango de categorías, establecer chart.category_data una vez es más conciso. Cuando las series tienen rangos de categorías diferentes — por ejemplo, dos conjuntos de datos con periodos de tiempo distintos — use el argumento de palabra clave por serie en su lugar.

Posicionamiento del gráfico

Los cuatro parámetros posicionales de cada método add_* definen un rectángulo delimitador en la hoja, medido en índices de fila y columna basados en cero:

add_bar(top_row, left_col, bottom_row, right_col)
ParámetroSignificado
top_rowÍndice basado en cero de la primera fila ocupada por el gráfico
left_colÍndice basado en cero de la columna más a la izquierda
bottom_rowÍndice basado en cero de la última fila ocupada por el gráfico
right_colÍndice basado en cero de la columna más a la derecha

Un patrón común es colocar el gráfico directamente debajo de los datos. Si sus datos terminan en la fila 6 de Excel (índice de fila basado en cero 5), comience el gráfico en 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")

Haz que el gráfico sea lo suficientemente alto para ser legible: una altura de al menos 15 filas
(bottom_row - top_row >= 15) y un ancho de al menos 6 columnas es un punto de partida razonable.

Errores comunes

IncorrectoCorrectoPor qué
ws.charts.add(ChartType.COLUMN, ...)ws.charts.add_bar(...)No llame a ws.charts.add(ChartType.X, ...) directamente para tipos no compatibles — generará NotImplementedError para 11 de 16 tipos de gráfico. Use add_bar(), add_line(), add_pie(), add_area() o add_stock() en su lugar.
chart.title.text = "My Chart"chart.title = "My Chart"chart.title es una propiedad de cadena simple, no un objeto con una subpropiedad .text.
chart.n_series.add("B2:B5", "A2:A5", "Revenue")chart.n_series.add("B2:B5", category_data="A2:A5", name="Revenue")Los segundo y tercer parámetros deben pasarse como argumentos con nombre para evitar ambigüedad.
chart = ws.charts.add_bar(0, 0, 15, 7) (superpone datos)Coloque top_row debajo de la última fila de datosUn gráfico que superpone datos oculta valores y produce diseños confusos.
chart.legend_position = "bottom" sin chart.show_legend = TrueEstablezca chart.show_legend = True primerolegend_position no tiene efecto cuando show_legend está False.

Ver también

 Español