Crea grafici a cascata in Word utilizzando Python

Un grafico a cascata mostra come un valore iniziale cambia attraverso una serie di aumenti e diminuzioni. Ad esempio, è possibile utilizzarne uno in un rapporto finanziario per mostrare come vendite, spese e altri redditi contribuiscono a un saldo finale.

In questo tutorial, creerai un grafico a cascata in un documento Word usando Python e Aspose.Words for Python via .NET. Imparerai anche come identificare i punti totali nel grafico e ispezionare i grafici a cascata nei documenti esistenti.

Libreria Python per creare diagrammi a cascata in Word

Aspose.Words for Python via .NET ti consente di creare e modificare documenti Word in Python. Puoi usarlo per aggiungere grafici ai report e lavorare con le serie di grafici e i punti dati.

Installa la libreria da PyPI:

pip install aspose-words

Utilizza Aspose.Words for Python via .NET 26.10 o versioni successive per il tutorial completo. Questa versione ha introdotto le API utilizzate per verificare se un punto del grafico a cascata è un totale.

Per i requisiti della piattaforma e altri dettagli di installazione, vedere la documentazione di installazione.

Comprendere il grafico a cascata di esempio

Gli esempi utilizzano i seguenti dati per mostrare le variazioni da un saldo di apertura a un saldo di chiusura:

I punti di vendite, spese e altri redditi rappresentano variazioni. Il saldo di apertura, il subtotale e il saldo di chiusura rappresentano valori in fasi particolari.

Per creare la serie del grafico, fornirai tre elenchi nello stesso ordine:

• Categories: Etichette per i punti del grafico.
• Values: Le modifiche e i valori totali forniti esplicitamente.
• Total flags: Valori booleani che designano i punti corrispondenti come totali.

Le flag identificano i punti totali; non li calcolano. In questo esempio, il subtotale è fornito come 120 e il saldo finale è fornito come 130.

Crea un grafico a cascata in Word usando Python

Segui questi passaggi per creare il grafico:

1. Crea un Document e un DocumentBuilder.
2. Inserisci un grafico usando ChartType.WATERFALL.
3. Imposta il titolo del grafico e cancella la serie predefinita.
4. Aggiungi le categorie, i valori e i flag di totale.
5. Salva il documento come file DOCX.

Il seguente esempio crea il grafico completo:

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

Il metodo add() specifico per il waterfall accetta il nome della serie, le categorie, i valori e i flag Booleani. Ogni elemento a un dato indice descrive lo stesso punto del grafico. Sebbene l’argomento Booleano sia denominato is_subtotal, l’esempio documentato lo utilizza per designare il valore iniziale, un subtotale intermedio e il valore finale come totali.

Il file risultante waterfall-chart.docx contiene un grafico a sei punti che mostra il saldo di apertura, le variazioni, il subtotale e il saldo di chiusura.

Verifica se un punto del grafico a cascata è un totale

Puoi verificare la designazione di ciascun punto con series.is_total(index). Aggiungi il seguente ciclo dopo la chiamata chart.series.add(...) nell’esempio precedente:

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

Per i dati di esempio, l’output previsto è:

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

Il metodo is_total() accetta un indice a base zero e restituisce True se il punto è designato come totale. Non identifica se il punto è un saldo di apertura, un subtotale intermedio o un totale finale.

Verifica un totale usando ChartDataPoint.is_total

Se hai già un punto dati del grafico, puoi leggere la sua proprietà is_total. L’esempio seguente verifica il subtotale all’indice 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 è una proprietà read-only per i grafici a cascata. Come series.is_total(index), segnala la designazione del punto; non imposta né calcola il totale.

Ispeziona un grafico a cascata in un documento Word esistente

È possibile caricare anche un documento Word esistente e cercare al suo interno le serie di grafici a cascata. L’esempio autonomo seguente controlla ogni forma, ignora le forme senza grafici e ispeziona ogni serie a cascata che trova.

Sostituisci waterfall-chart.docx con il percorso del tuo documento:

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

L’esempio riporta ogni punto tramite il suo indice basato su zero. Elabora più serie waterfall se sono presenti e stampa un messaggio se non ne trova alcuna. La proprietà series_type consente al codice di verificare ChartSeriesType.WATERFALL prima di chiamare is_total().

Ottieni una licenza gratuita

Puoi richiedere una licenza temporanea gratuita per valutare Aspose.Words for Python via .NET. Applica la licenza nella tua applicazione prima di eseguire gli esempi.

Conclusione

È possibile creare un grafico a cascata in un documento Word utilizzando Python e identificare i suoi punti totali in modo programmatico. Utilizza lo stesso approccio per aggiungere grafici ai report generati o per ispezionare le serie a cascata nei documenti esistenti.

Domande frequenti

Come creo un grafico a cascata in Word usando Python?

Inserisci un grafico usando ChartType.WATERFALL, aggiungi una serie con categorie, valori e flag di totale, e salva il documento come file DOCX.

Come specificare i punti totali in un grafico a cascata?

Passa una lista di valori booleani tramite l’argomento is_subtotal quando aggiungi la serie. Imposta un elemento su True per ogni punto che dovrebbe essere designato come totale.

Come posso verificare se un punto del grafico a cascata è un totale?

Chiama series.is_total(index) con l’indice zero‑based del punto, oppure leggi la proprietà is_total del suo oggetto data‑point.

Le API is_total impostano o calcolano i totali?

No. Segnalano se un punto è designato come totale. Fornisci i valori e i loro flag di totale quando crei la serie.

Posso ispezionare un grafico a cascata in un documento Word esistente?

Sì. Carica il documento, trova le forme che contengono grafici e controlla ogni serie per ChartSeriesType.WATERFALL prima di esaminarne i punti.

Vedi anche

• Lavorare con i grafici in Aspose.Words for Python
• Riferimento API per ChartSeries.is_total
• Riferimento API per ChartDataPoint.is_total
• Forum di supporto Aspose.Words