Aspose.Cells FOSS
Python
开发者指南
使用图表

使用图表

概述

Aspose.Cells FOSS 使用每种图表类型对应的方法 API。不是使用通用的 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 对象，您可以在保存之前进一步配置它。

限制： 仅 LINE、BAR、PIE、AREA 和 STOCK 图表类型可以保存为 XLSX。调用 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-level category data 作为默认适用于所有系列:

chart.category_data = "A2:A5"

Series-level category data (通过 category_data 关键字参数传递给 n_series.add) 覆盖该特定系列的图表级设置：

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

当所有系列共享相同的类别范围时，设置 chart.category_data
一次更简洁。当系列具有不同的类别范围——例如，
两个具有不同时间段的数据集——请改用每个系列的关键字参数
即可。

图表定位

每个 add_* 方法的四个位置参数定义了工作表中的一个边界矩形，以零基的行和列索引进行测量：

add_bar(top_row, left_col, bottom_row, right_col)
ParameterMeaning
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, ...) 处理不受支持的类型——它会在 16 种图表类型中的 11 种抛出 NotImplementedError。请改用 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当 show_legend 为 False 时，legend_position 不会产生任何效果。

另请参见

 中文