Ett waterfall-diagram visar hur ett startvärde förändras genom en serie ökningar och minskningar. Till exempel kan du använda ett i en finansiell rapport för att visa hur försäljning, kostnader och annan inkomst bidrar till en slutbalans.
I den här handledningen kommer du att skapa ett vattenfallsdiagram i ett Word‑dokument med Python och Aspose.Words for Python via .NET. Du kommer också att lära dig hur du identifierar totala punkter i diagrammet och inspekterar vattenfallsdiagram i befintliga dokument.
Python‑bibliotek för att skapa waterfall‑diagram i Word
Aspose.Words for Python via .NET låter dig skapa och ändra Word-dokument i Python. Du kan använda den för att lägga till diagram i rapporter och arbeta med diagramserier och datapunkter.
Installera biblioteket från PyPI:
pip install aspose-words
Använd Aspose.Words for Python via .NET 26.10 or later för den kompletta handledningen. Denna version introducerade API:erna som används för att kontrollera om en vattenfallsdiagram‑punkt är en total.
För plattformskrav och andra installationsdetaljer, se installationsdokumentation.
Förstå exempel på vattenfallsdiagram
Exemplen använder följande data för att visa förändringar från ett öppningssaldo till ett slutsaldo:
| Kategori | Värde | Punkt typ |
|---|---|---|
| Ingående saldo | 100 | Totalt |
| Försäljning | +40 | Ökning |
| Utgifter | −20 | Minskning |
| Delsumma | 120 | Totalt |
| Övriga intäkter | +10 | Ökning |
| Utgående saldo | 130 | Totalt |
Försäljnings-, kostnads- och övriga intäktspunkter representerar förändringar. Ingående saldo, delsumma och slutsaldo representerar värden vid specifika stadier.
För att skapa diagramserien ska du ange tre listor i samma ordning:
- Kategorier: Etiketter för diagrampunkterna.
- Värden: Ändringarna och uttryckligen angivna totala värden.
- Totala flaggor: Booleska värden som markerar motsvarande punkter som totaler.
Flaggorna identifierar totalpoäng; de inte beräknar dem. I det här exemplet anges delbeloppet som 120, och slutsaldot anges som 130.
Skapa ett vattenfallsdiagram i Word med Python
Följ dessa steg för att skapa diagrammet:
- Skapa ett
Documentoch enDocumentBuilder. - Infoga ett diagram med
ChartType.WATERFALL. - Ställ in diagramtitel och rensa standardserien.
- Lägg till kategorierna, värdena och totalflaggorna.
- Spara dokumentet som en DOCX‑fil.
Följande exempel skapar hela diagrammet:
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")
Den vattenfalls‑specifika add()‑metoden accepterar seriernamnet, kategorier, värden och booleska flaggor. Varje objekt på ett givet index beskriver samma diagrampunkt. Även om det booleska argumentet heter is_subtotal, använder det dokumenterade exemplet det för att ange startvärdet, ett mellanstegssubtotal och det slutliga värdet som totaler.
Den resulterande waterfall-chart.docx innehåller ett sexpunktsdiagram som visar ingående saldo, förändringar, delsumma och slutsaldo.
Skapa vattenfallsdiagram i Word med Python.
Kontrollera om en punkt i ett vattenfallsdiagram är en total
Du kan kontrollera varje punkts beteckning med series.is_total(index). Lägg till följande loop efter anropet chart.series.add(...) i föregående exempel:
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}")
För exempeldata är det förväntade resultatet:
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()-metoden tar ett nollbaserat index och returnerar True om punkten är markerad som en total. Den identifierar inte om punkten är en öppningsbalans, ett mellanstegssubtotal eller en slutlig total.
Kontrollera en total med ChartDataPoint.is_total
Om du redan har en diagramdatapunkt kan du läsa dess is_total-egenskap. Följande exempel kontrollerar delsumman på index 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 är en skrivskyddad egenskap för vattenfallsdiagram. Liksom series.is_total(index) rapporterar den punktens beteckning; den ställer inte in eller beräknar totalen.
Inspektera ett vattenfallsdiagram i ett befintligt Word-dokument
Du kan också läsa in ett befintligt Word‑dokument och söka efter vattenfallsdiagramserier. Följande fristående exempel kontrollerar varje form, hoppar över former utan diagram och granskar varje vattenfallsserie som den hittar.
Ersätt waterfall-chart.docx med sökvägen till ditt dokument:
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.")
Exemplet rapporterar varje punkt med dess nollbaserade index. Det bearbetar flera waterfall‑serier om de finns och skriver ut ett meddelande om det inte hittar någon. series_type‑egenskapen låter koden kontrollera ChartSeriesType.WATERFALL innan is_total() anropas.
Få en gratis licens
Du kan begära en gratis tillfällig licens för att utvärdera Aspose.Words for Python via .NET. Applicera licensen i din applikation innan du kör exemplen.
Slutsats
Du kan skapa ett waterfall‑diagram i ett Word‑dokument med Python och identifiera dess totala punkter programmässigt. Använd samma metod för att lägga till diagram i genererade rapporter eller inspektera waterfall‑serier i befintliga dokument.
Vanliga frågor
Hur skapar jag ett vattenfallsdiagram i Word med Python?
Infoga ett diagram med ChartType.WATERFALL, lägg till en serie med kategorier, värden och totalflaggor, och spara dokumentet som en DOCX-fil.
Hur specificerar jag totala poäng i ett waterfall-diagram?
Skicka en boolesk lista via argumentet is_subtotal när du lägger till serien. Ställ in ett värde till True för varje punkt som ska betecknas som en total.
Hur kan jag kontrollera om en punkt i ett vattenfallsdiagram är en total?
Anropa series.is_total(index) med punktens nollbaserade index, eller läs is_total‑egenskapen på dess datapunktobjekt.
Ställer is_total‑API:erna in eller beräknar de totaler?
Nej. De rapporterar om en punkt är markerad som en total. Ange värdena och deras totalflaggor när du skapar serien.
Kan jag inspektera ett vattenfallsdiagram i ett befintligt Word-dokument?
Ja. Ladda dokumentet, hitta former som innehåller diagram och kontrollera varje serie för ChartSeriesType.WATERFALL innan du undersöker dess punkter.