Gerenciar Rótulos de Dados de Gráficos em Apresentações Usando PHP
Introdução
Os rótulos de dados exibem informações sobre séries do gráfico e pontos de dados individuais, ajudando os leitores a identificar valores e entender o gráfico. Este artigo explica como formatar valores, exibir percentuais, 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 categorias 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 da série. 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 milhar e duas casas decimais sem alterar os valores subjacentes.
use aspose\slides\Presentation;
use aspose\slides\ChartType;
use aspose\slides\SaveFormat;
$presentation = new 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();
}
Exibir Percentual como Rótulos
Para um gráfico de colunas empilhadas, calcule cada valor como percentual 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 percentuais com duas casas decimais em fonte de 8 pt. 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.
use aspose\slides\Presentation;
use aspose\slides\ChartType;
use aspose\slides\Portion;
use aspose\slides\SaveFormat;
$presentation = new Presentation();
try {
$slide = $presentation->getSlides()->get_Item(0);
$chart = $slide->getShapes()->addChart(ChartType::StackedColumn, 20, 20, 400, 400);
$categoryCount = java_values($chart->getChartData()->getCategories()->size());
$categoryTotals = array_fill(0, $categoryCount, 0.0);
for ($k = 0; $k < $categoryCount; $k++) {
for ($i = 0; $i < java_values($chart->getChartData()->getSeries()->size()); $i++) {
$series = $chart->getChartData()->getSeries()->get_Item($i);
$pointValue = java_values($series->getDataPoints()->get_Item($k)->getValue()->getData());
$categoryTotals[$k] += $pointValue;
}
}
for ($x = 0; $x < java_values($chart->getChartData()->getSeries()->size()); $x++) {
$series = $chart->getChartData()->getSeries()->get_Item($x);
$series->getLabels()->getDefaultDataLabelFormat()->setShowLegendKey(false);
for ($j = 0; $j < java_values($series->getDataPoints()->size()); $j++) {
$label = $series->getDataPoints()->get_Item($j)->getLabel();
if ($categoryTotals[$j] == 0) {
continue;
}
$pointValue = java_values($series->getDataPoints()->get_Item($j)->getValue()->getData());
$dataPointPercent = ($pointValue / $categoryTotals[$j]) * 100;
$portion = new Portion();
$portion->setText(sprintf("%.2F %%", $dataPointPercent));
$portion->getPortionFormat()->setFontHeight(8);
$label->getTextFrameForOverriding()->setText("");
$paragraph = $label->getTextFrameForOverriding()->getParagraphs()->get_Item(0);
$paragraph->getPortions()->add($portion);
$label->getDataLabelFormat()->setShowValue(true);
$label->getDataLabelFormat()->setShowSeriesName(false);
$label->getDataLabelFormat()->setShowPercentage(false);
$label->getDataLabelFormat()->setShowLegendKey(false);
$label->getDataLabelFormat()->setShowCategoryName(false);
$label->getDataLabelFormat()->setShowBubbleSize(false);
}
}
$presentation->save("DisplayPercentageAsLabels_out.pptx", SaveFormat::Pptx);
} finally {
$presentation->dispose();
}
Definir Símbolo de Percentual nos Rótulos de Dados do Gráfico
Quando os valores são armazenados como frações, use setNumberFormat para exibir percentuais. Passe false para setNumberFormatLinkedToSource para aplicar o formato do rótulo independentemente das células de origem.
Este exemplo cria um gráfico de colunas empilhadas a 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, 10 pt.
use aspose\slides\Presentation;
use aspose\slides\ChartType;
use aspose\slides\FillType;
use aspose\slides\SaveFormat;
$presentation = new 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();
$worksheetIndex = 0;
for ($i = 0; $i < 4; $i++) {
$categoryCell = $workbook->getCell($worksheetIndex, $i + 1, 0, "Category " . ($i + 1));
$chart->getChartData()->getCategories()->add($categoryCell);
}
$colors = java("java.awt.Color");
$seriesNames = [ "Reds", "Blues" ];
$seriesColors = [ $colors->RED, $colors->BLUE ];
$values = [ [ 0.30, 0.50, 0.80, 0.65 ], [ 0.70, 0.50, 0.20, 0.35 ] ];
for ($i = 0; $i < count($seriesNames); $i++) {
$seriesCell = $workbook->getCell($worksheetIndex, 0, $i + 1, $seriesNames[$i]);
$series = $chart->getChartData()->getSeries()->add($seriesCell, $chart->getType());
for ($j = 0; $j < 4; $j++) {
$valueCell = $workbook->getCell($worksheetIndex, $j + 1, $i + 1, $values[$i][$j]);
$series->getDataPoints()->addDataPointForBarSeries($valueCell);
}
$series->getFormat()->getFill()->setFillType(FillType::Solid);
$series->getFormat()->getFill()->getSolidFillColor()->setColor($seriesColors[$i]);
$labelFormat = $series->getLabels()->getDefaultDataLabelFormat();
$labelFormat->setShowValue(true);
$labelFormat->setNumberFormatLinkedToSource(false);
$labelFormat->setNumberFormat("0.0%");
$labelFormat->getTextFormat()->getPortionFormat()->setFontHeight(10);
$labelFormat->getTextFormat()->getPortionFormat()->getFillFormat()->setFillType(FillType::Solid);
$labelFormat->getTextFormat()->getPortionFormat()->getFillFormat()->getSolidFillColor()->setColor($colors->WHITE);
}
$presentation->save("SetDataLabelsPercentageSign_out.pptx", SaveFormat::Pptx);
} finally {
$presentation->dispose();
}
Ler o Texto Real dos Rótulos de Dados
Use getActualLabelText para obter o texto produzido pelas configurações de um rótulo de dados. Isso é útil ao extrair rótulos para relatórios, pesquisar conteúdo de apresentações ou validar gráficos gerados. No exemplo abaixo, o formato padrão de rótulo de dados combina o nome de cada categoria, o nome da série e o valor. Um ponto formata seu valor como percentual, e outro usa texto personalizado de getTextFrameForOverriding.
use aspose\slides\Presentation;
use aspose\slides\ChartType;
$presentation = new 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();
$firstCategoryCell = $workbook->getCell(0, 1, 0, "Q1");
$chart->getChartData()->getCategories()->add($firstCategoryCell);
$secondCategoryCell = $workbook->getCell(0, 2, 0, "Q2");
$chart->getChartData()->getCategories()->add($secondCategoryCell);
$northSeriesCell = $workbook->getCell(0, 0, 1, "North");
$north = $chart->getChartData()->getSeries()->add($northSeriesCell, $chart->getType());
$northFirstValueCell = $workbook->getCell(0, 1, 1, 0.25);
$north->getDataPoints()->addDataPointForBarSeries($northFirstValueCell);
$northSecondValueCell = $workbook->getCell(0, 2, 1, 0.75);
$north->getDataPoints()->addDataPointForBarSeries($northSecondValueCell);
$southSeriesCell = $workbook->getCell(0, 0, 2, "South");
$south = $chart->getChartData()->getSeries()->add($southSeriesCell, $chart->getType());
$southFirstValueCell = $workbook->getCell(0, 1, 2, 0.40);
$south->getDataPoints()->addDataPointForBarSeries($southFirstValueCell);
$southSecondValueCell = $workbook->getCell(0, 2, 2, 0.60);
$south->getDataPoints()->addDataPointForBarSeries($southSecondValueCell);
for ($i = 0; $i < java_values($chart->getChartData()->getSeries()->size()); $i++) {
$series = $chart->getChartData()->getSeries()->get_Item($i);
$format = $series->getLabels()->getDefaultDataLabelFormat();
$format->setShowCategoryName(true);
$format->setShowSeriesName(true);
$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 ($i = 0; $i < java_values($chart->getChartData()->getSeries()->size()); $i++) {
$series = $chart->getChartData()->getSeries()->get_Item($i);
for ($j = 0; $j < java_values($series->getDataPoints()->size()); $j++) {
$point = $series->getDataPoints()->get_Item($j);
$label = $point->getLabel();
if (!java_values($label->isVisible())) {
continue;
}
echo "Value: " . java_values($point->getValue()->getData()) . "; label: " . java_values($label->getActualLabelText()) . PHP_EOL;
}
}
} finally {
$presentation->dispose();
}
O número armazenado em um ponto de dado 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 de rótulo gerado. getActualLabelText devolve a string resultante do rótulo em qualquer caso. Verifique isVisible separadamente, como mostrado acima, quando desejar extrair apenas rótulos visíveis.
Controlar Rótulos de Dados Além do Máximo do Eixo
Quando você limita manualmente o intervalo de um 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.
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 em 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 a nível de 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.
use aspose\slides\Presentation;
use aspose\slides\ChartType;
use aspose\slides\LegendDataLabelPosition;
use aspose\slides\SaveFormat;
$presentation = new 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();
$firstCategory = $workbook->getCell(0, 1, 0, "Within range");
$secondCategory = $workbook->getCell(0, 2, 0, "Above maximum");
$chart->getChartData()->getCategories()->add($firstCategory);
$chart->getChartData()->getCategories()->add($secondCategory);
$seriesName = $workbook->getCell(0, 0, 1, "Values");
$series = $chart->getChartData()->getSeries()->add($seriesName, $chart->getType());
$firstValue = $workbook->getCell(0, 1, 1, 60);
$secondValue = $workbook->getCell(0, 2, 1, 120);
$series->getDataPoints()->addDataPointForBarSeries($firstValue);
$series->getDataPoints()->addDataPointForBarSeries($secondValue);
$series->getLabels()->getDefaultDataLabelFormat()->setShowValue(true);
$series->getLabels()->getDefaultDataLabelFormat()->setPosition(LegendDataLabelPosition::OutsideEnd);
$chart->getAxes()->getVerticalAxis()->setAutomaticMaxValue(false);
$chart->getAxes()->getVerticalAxis()->setMaxValue(100);
$chart->setShowDataLabelsOverMaximum(true);
$secondSlide = $presentation->getSlides()->addClone($slide);
$secondChart = $secondSlide->getShapes()->get_Item(0);
$secondChart->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 continua 100 e o segundo ponto de dado permanece 120 em ambos os casos.
| setShowDataLabelsOverMaximum(true) | setShowDataLabelsOverMaximum(false) |
|---|---|
 |
 |
Tipo de Gráfico
Este exemplo usa um gráfico de colunas 2D com 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 dos rótulos do eixo horizontal para 500. Essa configuração afeta os rótulos do eixo de categorias, não os rótulos vinculados a pontos de dados individuais.
use aspose\slides\Presentation;
use aspose\slides\ChartType;
use aspose\slides\SaveFormat;
$presentation = new 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 ligação.
Este exemplo exibe o valor do primeiro ponto de dado, 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.
use aspose\slides\Presentation;
use aspose\slides\ChartType;
use aspose\slides\LegendDataLabelPosition;
use aspose\slides\SaveFormat;
$presentation = new 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();
}
FAQ
Como impedir que os rótulos de dados se sobreponham em gráficos densos?
Combine posicionamento automático de rótulos, linhas de ligação e redução do tamanho da fonte; se necessário, oculte alguns campos (por exemplo, a categoria) ou mostre rótulos apenas para valores extremos ou pontos-chave.
Como desabilitar 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 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.