Um gráfico de cascata mostra como um valor inicial muda ao longo de uma série de aumentos e diminuições. Por exemplo, você pode usar um em um relatório financeiro para mostrar como vendas, despesas e outras receitas contribuem para o saldo final.

Neste tutorial, você criará um gráfico de cascata em um documento Word usando Python e Aspose.Words for Python via .NET. Você também aprenderá como identificar pontos totais no gráfico e inspecionar gráficos de cascata em documentos existentes.

Biblioteca Python para Criar Gráficos de Cascata no Word

Aspose.Words for Python via .NET permite criar e modificar documentos Word em Python. Você pode usá-lo para adicionar gráficos a relatórios e trabalhar com séries de gráficos e pontos de dados.

Instale a biblioteca a partir do PyPI:

pip install aspose-words

Use Aspose.Words for Python via .NET 26.10 or later para o tutorial completo. Esta versão introduziu as APIs usadas para verificar se um ponto de gráfico de cascata é um total.

Para requisitos de plataforma e outros detalhes de instalação, veja a documentação de instalação.

Entenda o Gráfico de Cascata de Exemplo

Os exemplos utilizam os seguintes dados para mostrar as alterações de um saldo de abertura para um saldo de fechamento:

CategoriaValorTipo de ponto
Saldo inicial100Total
Vendas+40Aumento
Despesas−20Diminuição
Subtotal120Total
Outras receitas+10Aumento
Saldo final130Total

Os pontos de vendas, despesas e outras receitas representam alterações. O saldo de abertura, subtotal e saldo de fechamento representam valores em estágios específicos.

Para criar a série de gráfico, você fornecerá três listas na mesma ordem:

  • Categories: Rótulos para os pontos do gráfico.
  • Values: As alterações e valores totais fornecidos explicitamente.
  • Total flags: Valores booleanos que designam os pontos correspondentes como totais.

Os indicadores identificam os pontos totais; eles não os calculam. Neste exemplo, o subtotal é fornecido como 120, e o saldo final é fornecido como 130.

Criar um Gráfico Cascata no Word Usando Python

Siga estas etapas para criar o gráfico:

  1. Crie um Document e um DocumentBuilder.
  2. Insira um gráfico usando ChartType.WATERFALL.
  3. Defina o título do gráfico e limpe a série padrão.
  4. Adicione as categorias, valores e indicadores de total.
  5. Salve o documento como um arquivo DOCX.

O exemplo a seguir cria o gráfico 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")

O método add() específico para waterfall aceita o nome da série, categorias, valores e flags booleanas. Cada item em um determinado índice descreve o mesmo ponto do gráfico. Embora o argumento booleano seja chamado is_subtotal, o exemplo documentado o utiliza para designar o valor inicial, um subtotal intermediário e o valor final como totais.

O documento resultante waterfall-chart.docx contém um gráfico de seis pontos mostrando o saldo inicial, as alterações, o subtotal e o saldo final.

Criar gráficos de cascata no Word usando Python.

Criar gráficos de cascata no Word usando Python.

Verificar se um ponto de gráfico Waterfall é um total

Você pode verificar a designação de cada ponto com series.is_total(index). Adicione o seguinte loop após a chamada chart.series.add(...) no exemplo anterior:

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

Para os dados de exemplo, a saída esperada é:

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

O método is_total() recebe um índice baseado em zero e retorna True se o ponto for designado como total. Ele não identifica se o ponto é um saldo de abertura, um subtotal intermediário ou um total final.

Verificar um Total Usando ChartDataPoint.is_total

Se você já tem um ponto de dados do gráfico, pode ler sua propriedade is_total. O exemplo a seguir verifica o subtotal no índice 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 é uma propriedade somente leitura para gráficos de cascata. Como series.is_total(index), ela relata a designação do ponto; não define nem calcula o total.

Inspecionar um Gráfico de Cascata em um Documento Word Existente

Você também pode carregar um documento Word existente e pesquisá‑lo em busca de séries de gráfico de cascata. O exemplo autônomo a seguir verifica cada forma, ignora formas sem gráficos e inspeciona cada série de cascata que encontrar.

Substitua waterfall-chart.docx pelo caminho do seu 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.")

O exemplo relata cada ponto pelo seu índice baseado em zero. Ele processa várias séries waterfall se estiverem presentes e imprime uma mensagem caso não encontre nenhuma. A propriedade series_type permite que o código verifique ChartSeriesType.WATERFALL antes de chamar is_total().

Obtenha uma Licença Gratuita

Você pode solicitar uma licença temporária gratuita para avaliar o Aspose.Words for Python via .NET. Aplique a licença em sua aplicação antes de executar os exemplos.

Conclusão

Você pode criar um gráfico de cascata em um documento Word usando Python e identificar seus pontos totais programaticamente. Use a mesma abordagem para adicionar gráficos a relatórios gerados ou inspecionar séries de cascata em documentos existentes.

Perguntas Frequentes

Como criar um gráfico de cascata no Word usando Python?

Insira um gráfico usando ChartType.WATERFALL, adicione uma série com categorias, valores e indicadores de total e salve o documento como um arquivo DOCX.

Como especificar pontos totais em um gráfico de cascata?

Passe uma lista booleana através do argumento is_subtotal ao adicionar a série. Defina uma entrada como True para cada ponto que deve ser designado como total.

Como posso verificar se um ponto de gráfico de cascata é um total?

Chame series.is_total(index) com o índice baseado em zero do ponto, ou leia a propriedade is_total do seu objeto de ponto de dados.

As APIs is_total definem ou calculam totais?

Não. Eles relatam se um ponto está designado como total. Forneça os valores e seus indicadores de total ao criar a série.

Posso inspecionar um gráfico de cascata em um documento Word existente?

Sim. Carregue o documento, encontre as formas que contêm gráficos e verifique cada série para ChartSeriesType.WATERFALL antes de examinar seus pontos.

Veja Também