Gerenciar Rótulos de Dados de Gráficos em Apresentações com Python
Introdução
Os rótulos de dados exibem informações sobre as séries do gráfico e pontos de dados individuais, ajudando os leitores a identificar valores e compreender o gráfico. Este artigo explica como formatar valores, exibir porcentagens, ler o texto do rótulo, controlar rótulos além do máximo do eixo, ajustar o espaçamento dos rótulos do eixo de categoria e posicionar rótulos de gráficos de pizza.
Definir Precisão de Dados nos Rótulos de Dados do Gráfico
Use setNumberFormatOfValues para formatar os valores das séries. Este exemplo cria um gráfico de linhas com dados padrão, exibe sua tabela de dados e habilita rótulos de valores para a primeira série. O formato #,##0.00 exibe um separador de milhares e duas casas decimais sem alterar os valores subjacentes.
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, Presentation, SaveFormat
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(0)
chart = slide.getShapes().addChart(ChartType.Line, 50, 50, 450, 300)
chart.setDataTable(True)
series = chart.getChartData().getSeries().get_Item(0)
series.setNumberFormatOfValues("#,##0.00")
series.getLabels().getDefaultDataLabelFormat().setShowValue(True)
presentation.save("PrecisionOfDatalabels_out.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()
Para formatar as células numéricas na pasta de trabalho incorporada de um gráfico, veja Definir Formatos Numéricos Personalizados para Células da Pasta de Trabalho. Esse exemplo também mostra rótulos de valor seguindo os formatos das células de origem enquanto preserva os valores numéricos armazenados.
Exibir Porcentagem como Rótulos
Para um gráfico de colunas empilhadas, calcule cada valor como porcentagem do total da sua categoria e atribua o texto ao quadro de texto retornado por getTextFrameForOverriding. Este exemplo usa os dados padrão do gráfico e exibe porcentagens com duas casas decimais em uma fonte de 8 pontos. Categorias com total zero são ignoradas para evitar divisão por zero. Recalcule o texto personalizado do rótulo se os dados do gráfico mudarem.
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, Portion, Presentation, SaveFormat
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(0)
chart = slide.getShapes().addChart(ChartType.StackedColumn, 20, 20, 400, 400)
chart_series = chart.getChartData().getSeries()
category_totals = [0.0] * chart.getChartData().getCategories().size()
for category_index in range(len(category_totals)):
for series_index in range(chart_series.size()):
data_point = chart_series.get_Item(series_index).getDataPoints().get_Item(category_index)
category_totals[category_index] += float(data_point.getValue().getData())
for series_index in range(chart_series.size()):
series = chart_series.get_Item(series_index)
series.getLabels().getDefaultDataLabelFormat().setShowLegendKey(False)
for point_index in range(series.getDataPoints().size()):
data_point = series.getDataPoints().get_Item(point_index)
label = data_point.getLabel()
if category_totals[point_index] == 0:
print(f"Cannot calculate a percentage for category {point_index}: the total is zero.")
continue
point_percentage = float(data_point.getValue().getData()) / category_totals[point_index] * 100
portion = Portion()
portion.setText(f"{point_percentage:.2f} %")
portion.getPortionFormat().setFontHeight(8)
label.getTextFrameForOverriding().setText("")
paragraph = label.getTextFrameForOverriding().getParagraphs().get_Item(0)
paragraph.getPortions().add(portion)
label_format = label.getDataLabelFormat()
label_format.setShowValue(True)
label_format.setShowSeriesName(False)
label_format.setShowPercentage(False)
label_format.setShowLegendKey(False)
label_format.setShowCategoryName(False)
label_format.setShowBubbleSize(False)
presentation.save("DisplayPercentageAsLabels_out.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()
Definir Sinal de Porcentagem com Rótulos de Dados do Gráfico
Quando os valores são armazenados como frações, use setNumberFormat para exibir porcentagens. Passe False para setNumberFormatLinkedToSource a fim de aplicar o formato do rótulo independentemente das células de origem.
Este exemplo cria um gráfico de colunas empilhadas 100 % com séries vermelha e azul em quatro categorias. Cada par de valores soma 1. O formato de rótulo 0.0% exibe 0.30 como 30.0 %, enquanto o eixo vertical usa duas casas decimais. Ambas as séries usam texto de rótulo branco, tamanho 10 pt.
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, FillType, Presentation, SaveFormat
Color = jpype.JClass("java.awt.Color")
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(0)
chart = slide.getShapes().addChart(ChartType.PercentsStackedColumn, 20, 20, 500, 400)
chart.getAxes().getVerticalAxis().setNumberFormatLinkedToSource(False)
chart.getAxes().getVerticalAxis().setNumberFormat("0.00%")
chart.getChartData().getSeries().clear()
chart.getChartData().getCategories().clear()
workbook = chart.getChartData().getChartDataWorkbook()
worksheet_index = 0
for i in range(4):
category_cell = workbook.getCell(worksheet_index, i + 1, 0, f"Category {i + 1}")
chart.getChartData().getCategories().add(category_cell)
series_names = ["Reds", "Blues"]
series_colors = [Color.RED, Color.BLUE]
values = [[0.30, 0.50, 0.80, 0.65], [0.70, 0.50, 0.20, 0.35]]
for i, series_name in enumerate(series_names):
series_cell = workbook.getCell(worksheet_index, 0, i + 1, series_name)
series = chart.getChartData().getSeries().add(series_cell, chart.getType())
for j, value in enumerate(values[i]):
value_cell = workbook.getCell(worksheet_index, j + 1, i + 1, jpype.JDouble(value))
series.getDataPoints().addDataPointForBarSeries(value_cell)
series.getFormat().getFill().setFillType(FillType.Solid)
series.getFormat().getFill().getSolidFillColor().setColor(series_colors[i])
label_format = series.getLabels().getDefaultDataLabelFormat()
label_format.setShowValue(True)
label_format.setNumberFormatLinkedToSource(False)
label_format.setNumberFormat("0.0%")
portion_format = label_format.getTextFormat().getPortionFormat()
portion_format.setFontHeight(10)
portion_format.getFillFormat().setFillType(FillType.Solid)
portion_format.getFillFormat().getSolidFillColor().setColor(Color.WHITE)
presentation.save("SetDataLabelsPercentageSign_out.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()
Ler o Texto Real dos Rótulos de Dados
Use getActualLabelText para recuperar o texto produzido pelas configurações de um rótulo de dados. Isso é útil ao extrair rótulos para relatórios, pesquisar conteúdo da apresentação ou validar gráficos gerados. No exemplo abaixo, o formato de rótulo de dados padrão combina o nome de cada categoria, o nome da série e o valor. Um ponto formata seu valor como porcentagem e outro usa texto personalizado de getTextFrameForOverriding.
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, Presentation
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(0)
chart = slide.getShapes().addChart(ChartType.ClusteredColumn, 20, 20, 500, 300)
chart.getChartData().getSeries().clear()
chart.getChartData().getCategories().clear()
workbook = chart.getChartData().getChartDataWorkbook()
first_category_cell = workbook.getCell(0, 1, 0, "Q1")
chart.getChartData().getCategories().add(first_category_cell)
second_category_cell = workbook.getCell(0, 2, 0, "Q2")
chart.getChartData().getCategories().add(second_category_cell)
north_series_cell = workbook.getCell(0, 0, 1, "North")
north = chart.getChartData().getSeries().add(north_series_cell, chart.getType())
north_first_value_cell = workbook.getCell(0, 1, 1, jpype.JDouble(0.25))
north.getDataPoints().addDataPointForBarSeries(north_first_value_cell)
north_second_value_cell = workbook.getCell(0, 2, 1, jpype.JDouble(0.75))
north.getDataPoints().addDataPointForBarSeries(north_second_value_cell)
south_series_cell = workbook.getCell(0, 0, 2, "South")
south = chart.getChartData().getSeries().add(south_series_cell, chart.getType())
south_first_value_cell = workbook.getCell(0, 1, 2, jpype.JDouble(0.40))
south.getDataPoints().addDataPointForBarSeries(south_first_value_cell)
south_second_value_cell = workbook.getCell(0, 2, 2, jpype.JDouble(0.60))
south.getDataPoints().addDataPointForBarSeries(south_second_value_cell)
for series in chart.getChartData().getSeries():
label_format = series.getLabels().getDefaultDataLabelFormat()
label_format.setShowCategoryName(True)
label_format.setShowSeriesName(True)
label_format.setShowValue(True)
north.getLabels().get_Item(1).getDataLabelFormat().setNumberFormatLinkedToSource(False)
north.getLabels().get_Item(1).getDataLabelFormat().setNumberFormat("0%")
south.getLabels().get_Item(0).getTextFrameForOverriding().setText("Reviewed")
for series in chart.getChartData().getSeries():
for point in series.getDataPoints():
label = point.getLabel()
if not label.isVisible():
continue
print(f"Value: {point.getValue().getData()}; label: {label.getActualLabelText()}")
finally:
presentation.dispose()
O número armazenado em um ponto de dados permanece 0.75, mesmo quando seu rótulo mostra 75% juntamente com os nomes da categoria e da série. Texto personalizado substitui o texto gerado do rótulo. getActualLabelText devolve a string resultante do rótulo em ambos os casos. Verifique isVisible separadamente, como mostrado acima, quando quiser extrair apenas rótulos visíveis.
Controlar Rótulos de Dados Além do Máximo do Eixo
Quando você limita manualmente um intervalo de eixo, alguns pontos de dados podem exceder seu máximo. Use setShowDataLabelsOverMaximum para controlar se seus rótulos de dados são exibidos. Essa configuração altera a visibilidade dos rótulos; não altera o intervalo do eixo nem os valores subjacentes dos dados.
O exemplo abaixo cria um gráfico de colunas agrupadas 2D com valores 60 e 120. Ele passa False para setAutomaticMaxValue e define o máximo como 100 com setMaxValue no eixo vertical. O primeiro slide permite rótulos além do máximo; uma cópia desse slide os desabilita. Ambos os slides são salvos em DataLabelsOverMaximum.pptx.
Habilite rótulos de valor com setShowValue. A configuração ao nível do gráfico não habilita a exibição de valores por si só nem sobrescreve a exibição desabilitada de um rótulo individual. Este exemplo habilita valores para toda a série e usa setPosition para posicionar os rótulos na extremidade externa de cada coluna.
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, LegendDataLabelPosition, Presentation, SaveFormat
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(0)
chart = slide.getShapes().addChart(ChartType.ClusteredColumn, 50, 50, 600, 400)
chart.setLegend(False)
chart.getChartData().getSeries().clear()
chart.getChartData().getCategories().clear()
workbook = chart.getChartData().getChartDataWorkbook()
first_category = workbook.getCell(0, 1, 0, "Within range")
second_category = workbook.getCell(0, 2, 0, "Above maximum")
chart.getChartData().getCategories().add(first_category)
chart.getChartData().getCategories().add(second_category)
series_name = workbook.getCell(0, 0, 1, "Values")
series = chart.getChartData().getSeries().add(series_name, chart.getType())
first_value = workbook.getCell(0, 1, 1, jpype.JDouble(60))
second_value = workbook.getCell(0, 2, 1, jpype.JDouble(120))
series.getDataPoints().addDataPointForBarSeries(first_value)
series.getDataPoints().addDataPointForBarSeries(second_value)
series.getLabels().getDefaultDataLabelFormat().setShowValue(True)
series.getLabels().getDefaultDataLabelFormat().setPosition(LegendDataLabelPosition.OutsideEnd)
chart.getAxes().getVerticalAxis().setAutomaticMaxValue(False)
chart.getAxes().getVerticalAxis().setMaxValue(100)
chart.setShowDataLabelsOverMaximum(True)
second_slide = presentation.getSlides().addClone(slide)
second_chart = second_slide.getShapes().get_Item(0)
second_chart.setShowDataLabelsOverMaximum(False)
presentation.save("DataLabelsOverMaximum.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()
As imagens a seguir mostram os slides salvos renderizados pelo Microsoft PowerPoint. Com True, o rótulo 120 fica visível no limite superior; com False, ele fica oculto. O rótulo 60 permanece visível, o máximo do eixo permanece 100 e o segundo ponto de dados permanece 120 em ambos os casos.
| setShowDataLabelsOverMaximum(True) | setShowDataLabelsOverMaximum(False) |
|---|---|
![]() |
![]() |
Chart Type
Este exemplo usa um gráfico de colunas 2D com um eixo de valores. Gráficos sem eixo de valores, como gráficos de pizza e rosquinha, não possuem um máximo de eixo para limitar dessa forma.Definir Distância do Rótulo a partir de um Eixo
Use setLabelOffset para controlar a distância entre os rótulos do eixo de categorias e o eixo. O valor é uma porcentagem do tamanho máximo da fonte dos rótulos do eixo. Este exemplo cria um gráfico de colunas agrupadas e define o deslocamento do rótulo do eixo horizontal para 500. Essa configuração afeta os rótulos do eixo de categorias, e não os rótulos vinculados a pontos de dados individuais.
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, Presentation, SaveFormat
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(0)
chart = slide.getShapes().addChart(ChartType.ClusteredColumn, 20, 20, 500, 300)
chart.getAxes().getHorizontalAxis().setLabelOffset(500)
presentation.save("SetCategoryAxisLabelDistance_out.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()
Ajustar Localização do Rótulo
Em um gráfico de pizza, ajuste as posições dos rótulos de dados para melhorar o espaçamento e criar espaço para as linhas de conexão.
Este exemplo exibe o valor do primeiro ponto de dados, coloca seu rótulo fora da fatia e ajusta seus deslocamentos horizontal e vertical usando setX e setY. Esses deslocamentos são relativos à largura e altura do gráfico, respectivamente.
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, LegendDataLabelPosition, Presentation, SaveFormat
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(0)
chart = slide.getShapes().addChart(ChartType.Pie, 50, 50, 200, 200)
series = chart.getChartData().getSeries()
label = series.get_Item(0).getLabels().get_Item(0)
label.getDataLabelFormat().setShowValue(True)
label.getDataLabelFormat().setPosition(LegendDataLabelPosition.OutsideEnd)
label.setX(0.71)
label.setY(0.04)
presentation.save("presentation.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()

Formatar Linhas de Conexão
Quando os rótulos de gráficos de pizza ficam fora de suas fatias, as linhas de conexão ajudam os leitores a associar cada valor à fatia correta. Uma cor contrastante e uma linha um pouco mais espessa podem tornar essas conexões mais fáceis de seguir, enquanto transparência e estilo tracejado mantêm as linhas visualmente discretas.
Use getLeaderLinesFormat para formatar linhas de conexão no nível da coleção de rótulos de dados da série. As configurações em series.getLabels().getLeaderLinesFormat().getLine() aplicam‑se à coleção, e não a um rótulo individual.
Este exemplo cria um gráfico de pizza com dados padrão, exibe valores fora das fatias e habilita setShowLeaderLines. Ele afasta dois rótulos de suas fatias usando deslocamentos setX e setY, expressos como frações da largura e altura do gráfico. Nenhuma apresentação de entrada é necessária.
O getFillFormat da linha define uma cor azul sólida com valor alfa 191 de 255, proporcionando aproximadamente 25 % de transparência. setWidth define a espessura para 2 pontos, e setDashStyle deixa a linha tracejada.
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, FillType, LegendDataLabelPosition, LineDashStyle, Presentation, SaveFormat
Color = jpype.JClass("java.awt.Color")
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(0)
chart = slide.getShapes().addChart(ChartType.Pie, 80, 50, 560, 400)
chart.setLegend(False)
series = chart.getChartData().getSeries().get_Item(0)
label_format = series.getLabels().getDefaultDataLabelFormat()
label_format.setShowValue(True)
label_format.setPosition(LegendDataLabelPosition.OutsideEnd)
label_format.setShowLeaderLines(True)
# Mova dois rótulos mais longe de suas fatias.
series.getLabels().get_Item(0).setX(0.10)
series.getLabels().get_Item(0).setY(-0.05)
series.getLabels().get_Item(1).setX(-0.10)
series.getLabels().get_Item(1).setY(0.05)
line = series.getLabels().getLeaderLinesFormat().getLine()
line.getFillFormat().setFillType(FillType.Solid)
color = Color(30, 90, 160, 191)
line.getFillFormat().getSolidFillColor().setColor(color)
line.setWidth(2)
line.setDashStyle(LineDashStyle.Dash)
presentation.save("FormattedLeaderLines.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()
Habilitar linhas de conexão não garante que uma linha aparecerá para cada rótulo. A visibilidade depende do posicionamento do rótulo e do comportamento de layout do gráfico. Neste exemplo, os dois rótulos deslocados têm linhas de conexão visíveis; os rótulos que permanecem próximos às suas fatias não precisam delas.
A imagem a seguir mostra o FormattedLeaderLines.pptx salvo, renderizado com Aspose.Slides:

Adicionar Várias Linhas de Rótulos de Dados Acima de um Gráfico de Colunas
Este exemplo cria um gráfico de colunas com duas linhas de rótulos de dados acima da área de plotagem. A Série A exibe as colunas visíveis, enquanto as Séries B e C fornecem os rótulos adicionais. Suas colunas são ocultadas removendo o preenchimento e o contorno. O método ChartSeriesGroup.setOverlap alinha as três séries aos mesmos centros de categoria.
As configurações de ChartPlotArea reservam espaço para as linhas de rótulos. Após Chart.validateChartLayout calcular as posições padrão, DataLabel.setX e DataLabel.setY preservam o alinhamento horizontal e aplicam deslocamentos verticais para organizar os rótulos em duas linhas. Os números permanecem rótulos de dados vinculados aos valores das séries; apenas os cabeçalhos das linhas são formas de texto separadas.
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, FillType, LayoutTargetType, LegendDataLabelPosition, Presentation, SaveFormat, ShapeType
Color = jpype.JClass("java.awt.Color")
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(0)
chart = slide.getShapes().addChart(ChartType.ClusteredColumn, 40, 40, 640, 200)
chart.setTitle(False)
chart.setLegend(False)
chart.getTextFormat().getPortionFormat().setFontHeight(12)
chart.getChartData().getSeries().clear()
chart.getChartData().getCategories().clear()
workbook = chart.getChartData().getChartDataWorkbook()
workbook.clear(0)
categories = ["North", "South", "East", "West"]
series_names = ["Series A", "Series B", "Series C"]
series_values = [[35, 42, 28, 47], [22, 31, 19, 26], [12, 16, 14, 18]]
for category_index, category in enumerate(categories):
category_cell = workbook.getCell(0, category_index + 1, 0, category)
chart.getChartData().getCategories().add(category_cell)
for series_index, series_name in enumerate(series_names):
series_cell = workbook.getCell(0, 0, series_index + 1, series_name)
series = chart.getChartData().getSeries().add(series_cell, ChartType.ClusteredColumn)
for category_index, value in enumerate(series_values[series_index]):
value_cell = workbook.getCell(0, category_index + 1, series_index + 1, jpype.JDouble(value))
series.getDataPoints().addDataPointForBarSeries(value_cell)
if series_index > 0:
# Oculte as colunas de B e C, mas mantenha seus rótulos de dados.
series.getFormat().getFill().setFillType(FillType.NoFill)
series.getFormat().getLine().getFillFormat().setFillType(FillType.NoFill)
label_format = series.getLabels().getDefaultDataLabelFormat()
label_format.setShowValue(True)
label_format.getTextFormat().getPortionFormat().setFontHeight(12)
label_fill = label_format.getTextFormat().getPortionFormat().getFillFormat()
label_fill.setFillType(FillType.Solid)
label_fill.getSolidFillColor().setColor(Color.BLACK)
label_format.setPosition(LegendDataLabelPosition.InsideBase)
# Alinhe as três séries ao mesmo centro de categoria.
chart.getChartData().getSeries().get_Item(0).getParentSeriesGroup().setOverlap(jpype.JByte(100))
# Use menos linhas de grade neste exemplo compacto.
chart.getAxes().getVerticalAxis().setAutomaticMajorUnit(False)
chart.getAxes().getVerticalAxis().setMajorUnit(10)
# Reserve espaço acima da área de plotagem para duas linhas de rótulos de dados.
chart.getPlotArea().setLayoutTargetType(LayoutTargetType.Inner)
chart.getPlotArea().setX(0.15)
chart.getPlotArea().setY(0.32)
chart.getPlotArea().setWidth(0.80)
chart.getPlotArea().setHeight(0.48)
chart.validateChartLayout()
for series_index in range(1, len(series_names)):
series = chart.getChartData().getSeries().get_Item(series_index)
row_top = 0.15 if series_index == 1 else 0.03
for category_index in range(len(categories)):
data_label = series.getDataPoints().get_Item(category_index).getLabel()
# Mantenha a posição horizontal padrão. Y é um deslocamento a partir de
# a posição padrão do rótulo, expressa como fração da altura do gráfico.
data_label.setX(0)
data_label.setY(row_top - data_label.getActualY() / chart.getHeight())
# Apenas o cabeçalho da linha é uma forma de texto separada.
heading_y = chart.getY() + row_top * chart.getHeight()
row_heading = slide.getShapes().addAutoShape(ShapeType.Rectangle, chart.getX(), heading_y, 85, 18)
row_heading.getFillFormat().setFillType(FillType.NoFill)
row_heading.getLineFormat().getFillFormat().setFillType(FillType.NoFill)
row_heading.addTextFrame(series_names[series_index])
row_heading.getTextFrame().getTextFrameFormat().setMarginTop(0)
row_heading.getTextFrame().getTextFrameFormat().setMarginBottom(0)
heading_format = row_heading.getTextFrame().getParagraphs().get_Item(0).getPortions().get_Item(0).getPortionFormat()
heading_format.setFontHeight(12)
heading_format.getFillFormat().setFillType(FillType.Solid)
heading_format.getFillFormat().getSolidFillColor().setColor(Color.BLACK)
presentation.save("multiple-rows-of-labels.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()

Perguntas Frequentes
Como posso impedir que os rótulos de dados se sobreponham em gráficos densos?
Combine o posicionamento automático de rótulos, linhas de conexão e redução do tamanho da fonte; se necessário, oculte alguns campos (por exemplo, a categoria) ou exiba rótulos somente para valores extremos ou pontos‑chave.
Como posso desativar rótulos apenas para valores zero, negativos ou vazios?
Filtre os pontos de dados antes de habilitar os rótulos e desative a exibição para valores iguais a 0, valores negativos ou valores ausentes de acordo com uma regra definida.
Como posso garantir um estilo de rótulo consistente ao exportar para PDF/imagens?
Defina explicitamente a família e o tamanho da fonte e verifique se a fonte está disponível no ambiente de renderização para evitar substituição.

