Aspose.Cells FOSS
Python
Руководство разработчика
Работа с диаграммами

Работа с диаграммами

Обзор

Aspose.Cells FOSS uses a method-per-chart-type API. Instead of a generic add(ChartType.X, ...) при вызове каждый тип диаграммы имеет собственный выделенный метод в рабочего листа charts коллекции:

МетодТип диаграммы
ws.charts.add_bar(top_row, left_col, bottom_row, right_col)Группированный столбец (гистограмма)
ws.charts.add_line(top_row, left_col, bottom_row, right_col)Линия
ws.charts.add_pie(top_row, left_col, bottom_row, right_col)Круговая
ws.charts.add_area(top_row, left_col, bottom_row, right_col)Область

Все четыре позиционных параметра описывают прямоугольную область на листе, где будет встроена диаграмма. Индексы строк и столбцов являются нумеруются с нуля. Каждый метод возвращает Chart объект, который вы далее настраиваете перед сохранением.

Ограничение: Можно сохранять в XLSX только типы диаграмм LINE, BAR, PIE, AREA и STOCK. Вызов wb.save() с рабочей книгой, содержащей любой другой тип диаграммы (например, SCATTER, WATERFALL, RADAR, TREEMAP, HISTOGRAM), вызовет NotImplementedError.

Добавление столбчатой диаграммы

Пример ниже записывает небольшой набор данных о доходах по продуктам, а затем добавляет столбчатую диаграмму, расположенную под данными.

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

Данные занимают строки 1–6 (нумерация с нуля строки 0–5), поэтому top_row=6 размещает график сразу ниже, не перекрывая данные.

Добавление линейной диаграммы

Линейные графики хорошо подходят для отображения тенденций во времени. Сигнатура вызова идентична add_bar — только имя метода меняется.

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

Заголовок диаграммы и легенда

Установите заголовок диаграммы, присвоив простую строку непосредственно chart.title. Эта свойство принимает str — не пытайтесь обращаться к вложенному свойству, такому как .title.text, которое не существует в этой библиотеке.

##Correct
chart.title = "Quarterly Sales"

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

Видимость и позиция легенды управляются двумя свойствами:

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

Чтобы полностью скрыть легенду, установите chart.show_legend = False. Это legend_position значение игнорируется, когда легенда скрыта.

Настройка серий данных

Используйте chart.n_series.add() для привязки диапазонов данных к диаграмме. Передайте все аргументы как именованные аргументы чтобы избежать путаницы с порядком расположения:

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

Вы можете добавить несколько серий в одну диаграмму, вызвав n_series.add больше более одного раза. Каждый вызов добавляет новую серию:

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

Данные категорий

Метки категорий можно задавать на уровне диаграммы или на уровне отдельного ряда.

Данные категорий уровня диаграммы применяется ко всем сериям по умолчанию:

chart.category_data = "A2:A5"

Данные категорий уровня серии (через category_data именованный аргумент n_series.add) переопределяет настройку уровня диаграммы для этой конкретной серии:

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

Когда все серии используют один и тот же диапазон категорий, установка chart.category_data один раз более лаконична. Когда у серий разные диапазоны категорий — например, два набора данных с разными временными периодами — используйте аргумент ключевого слова per-series вместо этого.

Размещение диаграммы

Четыре позиционных параметра для каждого add_* метод определяют ограничивающий прямоугольник в листе, измеряемый в индексах строк и столбцов, начинающихся с нуля:

add_bar(top_row, left_col, bottom_row, right_col)
ПараметрЗначение
top_rowИндекс, начинающийся с нуля, первой строки, занятой диаграммой
left_colИндекс, начинающийся с нуля, самой левой колонки
bottom_rowИндекс, начинающийся с нуля, последней строки, занятой диаграммой
right_colИндекс, начинающийся с нуля, самой правой колонки

Распространённый шаблон — размещать диаграмму непосредственно под данными. Если ваши данные заканчивается на строке Excel 6 (нумерация строк с нуля, индекс 5), начните диаграмму с 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")

Сделайте диаграмму достаточно высокой, чтобы её было удобно читать: высота минимум 15 строк (bottom_row - top_row >= 15) и ширина минимум 6 столбцов — разумная отправная точка.

Распространённые ошибки

НеправильноПравильноПочему
ws.charts.add(ChartType.COLUMN, ...)ws.charts.add_bar(...)Не вызывайте ws.charts.add(ChartType.X, ...) непосредственно для неподдерживаемых типов — это вызовет NotImplementedError для 11 из 16 типов диаграмм. Используйте add_bar(), add_line(), add_pie(), add_area(), или add_stock() вместо этого.
chart.title.text = "My Chart"chart.title = "My Chart"chart.title является простым строковым свойством, а не объектом с .text подсвойством.
chart.n_series.add("B2:B5", "A2:A5", "Revenue")chart.n_series.add("B2:B5", category_data="A2:A5", name="Revenue")Второй и третий параметры должны передаваться как именованные аргументы, чтобы избежать неоднозначности.
chart = ws.charts.add_bar(0, 0, 15, 7) (перекрывает данные)Разместить top_row под последней строкой данныхДиаграмма, перекрывающая данные, скрывает значения и приводит к запутанным макетам.
chart.legend_position = "bottom" без chart.show_legend = TrueУстановить chart.show_legend = True первыйlegend_position не оказывает эффекта, когда show_legend является False.

См. также

 Русский