瀑布图显示了起始值如何通过一系列的增加和减少而变化。例如，您可以在财务报告中使用它来展示销售额、费用和其他收入是如何共同构成期末余额的。

在本教程中，您将使用 Python 和 Aspose.Words for Python via .NET 在 Word 文档中创建瀑布图。您还将学习如何识别图表中的总计点以及检查现有文档中的瀑布图。

用于在 Word 中创建瀑布图的 Python 库

Aspose.Words for Python via .NET 让您能够在 Python 中创建和修改 Word 文档。您可以使用它向报告中添加图表，并处理图表系列和数据点。

从 PyPI 安装库：

pip install aspose-words

使用 Aspose.Words for Python via .NET 26.10 或更高版本 完整教程。本版本引入了用于检查瀑布图数据点是否为总计的 API。

有关平台要求和其他安装细节，请参阅安装文档。

了解示例瀑布图

这些示例使用以下数据来显示从期初余额到期末余额的变化：

类别数值点类型
期初余额100总计
销售额+40增加
费用−20减少
小计120总计
其他收入+10增加
期末余额130总计

销售、费用和其他收入点表示变动。期初余额、小计和期末余额表示特定阶段的数值。

要创建图表系列，您需要按相同顺序提供三个列表：

  • 类别: 图表点的标签。
  • 数值: 更改和显式提供的总计值。
  • 总计标志: 指定相应点为总计的布尔值。

这些标志用于标识总点数；它们 不 进行计算。在此示例中，小计提供为 120，而期末余额提供为 130。

使用 Python 在 Word 中创建瀑布图

按照以下步骤创建图表：

  1. 创建一个 Document 和一个 DocumentBuilder。
  2. 使用 ChartType.WATERFALL 插入图表。
  3. 设置图表标题并清除默认系列。
  4. 添加类别、数值和总计标记。
  5. 将文档保存为 DOCX 文件。

以下示例创建完整的图表：

import aspose.words as aw

# Create a document and document builder.
doc = aw.Document()
builder = aw.DocumentBuilder(doc)

# Insert a waterfall chart.
shape = builder.insert_chart(
    chart_type=aw.drawing.charts.ChartType.WATERFALL,
    width=500,
    height=350
)

chart = shape.chart
chart.title.text = "Balance Changes"

# Remove the default chart series.
chart.series.clear()

# Define categories, values, and total flags.
categories = [
    "Opening balance",
    "Sales",
    "Expenses",
    "Subtotal",
    "Other income",
    "Closing balance"
]

values = [100, 40, -20, 120, 10, 130]

total_flags = [True, False, False, True, False, True]

# Add the waterfall series.
series = chart.series.add(
    series_name="Balance",
    categories=categories,
    values=values,
    is_subtotal=total_flags
)

# Save the Word document.
doc.save("waterfall-chart.docx")

特定于瀑布图的 add() 方法接受系列名称、类别、数值和布尔标志。给定索引处的每个项描述相同的图表点。尽管布尔参数名为 is_subtotal，但文档示例将其用于指定起始值、中间小计以及最终值作为总计。

生成的 waterfall-chart.docx 包含一个六点图表，显示期初余额、变动、子总计和期末余额。

使用 Python 在 Word 中创建瀑布图。

使用 Python 在 Word 中创建瀑布图。

检查瀑布图点是否为合计

您可以使用 series.is_total(index) 检查每个点的指定。 在前面的示例中，在 chart.series.add(...) 调用之后添加以下循环：

for i in range(len(categories)):
    point_type = "Total" if series.is_total(i) else "Not a total"
    print(f"{categories[i]}: {values[i]} — {point_type}")

对于示例数据，预期的输出是：

Opening balance: 100 — Total
Sales: 40 — Not a total
Expenses: -20 — Not a total
Subtotal: 120 — Total
Other income: 10 — Not a total
Closing balance: 130 — Total

is_total() 方法接受 零基索引，如果该点被指定为合计则返回 True。它并不区分该点是期初余额、途中小计还是最终合计。

使用 ChartDataPoint.is_total 检查总计

如果您已经拥有图表数据点，可以读取其 is_total 属性。以下示例检查索引为 3 的小计：

is_subtotal = series.data_points[3].is_total
print(f"Subtotal is a total: {is_subtotal}")

Expected output:

Subtotal is a total: True

ChartDataPoint.is_total 是瀑布图的 只读 属性。类似 series.is_total(index)，它报告点的指定；它不设置或计算总计。

检查现有 Word 文档中的瀑布图

您还可以加载现有的 Word 文档并搜索其中的瀑布图系列。以下独立示例会检查每个形状，跳过没有图表的形状，并检查它找到的每个瀑布系列。

将 waterfall-chart.docx 替换为文档的路径：

import aspose.words as aw

# Load an existing Word document.
doc = aw.Document("waterfall-chart.docx")

found_waterfall_series = False

# Search the document's shapes.
shapes = doc.get_child_nodes(aw.NodeType.SHAPE, True)

for node in shapes:
    shape = node.as_shape()

if not shape.has_chart:
        continue

for series in shape.chart.series:
        if series.series_type != aw.drawing.charts.ChartSeriesType.WATERFALL:
            continue

found_waterfall_series = True
        print(f"Waterfall series: {series.name}")

for i in range(series.y_values.count):
            point_type = "Total" if series.is_total(i) else "Not a total"
            print(f"Point {i}: {point_type}")

if not found_waterfall_series:
    print("No waterfall chart series found.")

示例按零基索引报告每个点。如果存在多个瀑布系列，它会对它们进行处理；如果未找到任何系列，则打印一条消息。series_type 属性允许代码在调用 is_total() 之前检查 ChartSeriesType.WATERFALL。

获取免费许可证

您可以请求一个免费临时许可证，以评估 Aspose.Words for Python via .NET。在运行示例之前，请在您的应用程序中应用许可证。

结论

您可以使用 Python 在 Word 文档中创建瀑布图，并以编程方式识别其总点。使用相同的方法将图表添加到生成的报告中，或检查现有文档中的瀑布系列。

常见问题

如何使用 Python 在 Word 中创建瀑布图？

使用 ChartType.WATERFALL 插入图表，添加包含类别、数值和总计标记的系列，并将文档保存为 DOCX 文件。

如何在瀑布图中指定总点？

在添加序列时，通过 is_subtotal 参数传入布尔列表。将每个应标记为总计的点对应的条目设置为 True。

如何检查瀑布图点是否为总计？

调用 series.is_total(index) 并传入点的零基索引，或读取其数据点对象的 is_total 属性。

is_total API 是设置还是计算总计？

否。他们报告一个点是否被指定为总计。在创建系列时提供这些值及其总计标志。

我能在现有的 Word 文档中检查瀑布图吗？

是的。加载文档，查找包含图表的形状，并在检查其点之前检查每个系列是否为 ChartSeriesItemType.WATERFALL。

另请参阅