Управление сериями данных диаграмм в презентациях на PHP
Обзор
Диаграмма сохраняет отображаемые данные в рабочей книге данных диаграммы. A ChartSeries представляет один набор связанных значений, и каждый ChartDataPoint в серии ссылается на одну или несколько ячеек рабочей книги. Объекты ChartCategory предоставляют метки или значения группировки, общие для серии. Поэтому имя серии, категории и значения точек связаны с объектами ChartDataCell, а не хранятся только как отображаемый текст.
Для типичной категориальной диаграммы рабочая книга по умолчанию использует строку 0 для имен серий, столбец 0 для имен категорий и остальные ячейки для значений серий. Индексы листа, строки и столбца, передаваемые в ChartDataWorkbook.getCell, начинаются с нуля. Такой макет полезен при создании диаграммы с данными по умолчанию, но не следует предполагать, что каждая существующая диаграмма использует его. Для загруженной презентации проверьте ячейки, на которые ссылаются серии, категории и точки данных, прежде чем изменять значения в рабочей книге.
Настройки диаграммы имеют три разных уровня:
- Настройки уровня серии, такие как ChartSeries.getFormat, задают внешний вид по умолчанию для всех точек в одной серии.
- Настройки отдельной точки данных, такие как ChartDataPoint.getFormat, переопределяют внешний вид серии для одной точки.
- Настройки группы применяются к совместимым сериям, принадлежащим к одной ChartSeriesGroup. Получите доступ к группе через ChartSeries.getParentSeriesGroup, когда необходимо задать параметры, такие как перекрытие или ширина промежутка.
Если не заданы явные заливка точки или серии, стиль и тема диаграммы определяют автоматический внешний вид. Когда присутствуют как форматирование серии, так и точки, приоритет имеет форматирование точки для этой точки.
Установить перекрытие серии диаграммы
ChartSeries.getOverlap сообщает, насколько столбцы или столбцы перекрываются в 2‑D диаграмме, от -100 до 100 процентов. Это только для чтения проекция параметра в родительской группе серий. Используйте ChartSeriesGroup.setOverlap, чтобы обновить все совместимые серии в этой группе. Этот параметр применяется к типам диаграмм, отображающих сгруппированные столбцы или столбцы; он не влияет на несвязанные группы серий в комбинационной диаграмме.
Следующий пример задаёт перекрытие для группы, содержащей первую серию:
$firstSlideIndex = 0;
$firstSeriesIndex = 0;
$overlapPercent = 30;
$presentation = new Presentation();
try {
$slide = $presentation->getSlides()->get_Item($firstSlideIndex);
// Новая диаграмма содержит примерные серии, категории и значения.
$chart = $slide->getShapes()->addChart(ChartType::ClusteredColumn, 20, 20, 500, 200);
$series = $chart->getChartData()->getSeries()->get_Item($firstSeriesIndex);
$series->getParentSeriesGroup()->setOverlap($overlapPercent);
$presentation->save("series_overlap.pptx", SaveFormat::Pptx);
} finally {
if (!java_is_null($presentation)) {
$presentation->dispose();
}
}
Результат:
Изменить цвет заливки серии
Используйте ChartSeries.getFormat, чтобы задать заливку по умолчанию для всей серии. Если у точки уже есть явная заливка, её настройка ChartDataPoint.getFormat переопределяет заливку серии для этой точки.
Следующий пример применяет сплошную синюю заливку к первой серии:
$firstSlideIndex = 0;
$firstSeriesIndex = 0;
$blueColor = java("java.awt.Color")->BLUE;
$presentation = new Presentation();
try {
$slide = $presentation->getSlides()->get_Item($firstSlideIndex);
$chart = $slide->getShapes()->addChart(ChartType::ClusteredColumn, 20, 20, 500, 200);
$series = $chart->getChartData()->getSeries()->get_Item($firstSeriesIndex);
$series->getFormat()->getFill()->setFillType(FillType::Solid);
$series->getFormat()->getFill()->getSolidFillColor()->setColor($blueColor);
$presentation->save("series_color.pptx", SaveFormat::Pptx);
} finally {
if (!java_is_null($presentation)) {
$presentation->dispose();
}
}
Результат:
Изменить имя серии
Имя серии хранится в рабочей книге данных диаграммы и обычно отображается в легенде. В рабочей книге по умолчанию, созданной для группированной столбчатой диаграммы, ячейка B1 находится в строке 0, столбце 1 и содержит имя первой серии. Именованные переменные в следующем примере делают эту структуру явной:
$firstSlideIndex = 0;
$worksheetIndex = 0;
$seriesNameRowIndex = 0;
$firstSeriesColumnIndex = 1;
$presentation = new Presentation();
try {
$slide = $presentation->getSlides()->get_Item($firstSlideIndex);
$chart = $slide->getShapes()->addChart(ChartType::ClusteredColumn, 20, 20, 500, 200);
$workbook = $chart->getChartData()->getChartDataWorkbook();
$seriesNameCell = $workbook->getCell($worksheetIndex, $seriesNameRowIndex, $firstSeriesColumnIndex);
$seriesNameCell->setValue("Revenue");
$presentation->save("series_name.pptx", SaveFormat::Pptx);
} finally {
if (!java_is_null($presentation)) {
$presentation->dispose();
}
}
Вы также можете обновить ячейку, уже ссылку на которую имеет ChartSeries.getName. Такой подход позволяет избежать предположений о конкретных строке и столбце в существующей диаграмме:
$firstSlideIndex = 0;
$firstSeriesIndex = 0;
$firstNameCellIndex = 0;
$presentation = new Presentation();
try {
$slide = $presentation->getSlides()->get_Item($firstSlideIndex);
$chart = $slide->getShapes()->addChart(ChartType::ClusteredColumn, 20, 20, 500, 200);
$series = $chart->getChartData()->getSeries()->get_Item($firstSeriesIndex);
$seriesNameCell = $series->getName()->getAsCells()->get_Item($firstNameCellIndex);
$seriesNameCell->setValue("Revenue");
$presentation->save("series_name.pptx", SaveFormat::Pptx);
} finally {
if (!java_is_null($presentation)) {
$presentation->dispose();
}
}
Результат:
Создать серию с именем из нескольких ячеек
Составное имя серии полезно, когда название продукта и отчетный период хранятся в отдельных ячейках рабочей книги. Например, можно объединить Product A в B1 и 2026 в C1 в одно имя серии, при этом обе части остаются привязанными к своим исходным ячейкам.
Используйте ChartDataWorkbook::getCellCollection для получения диапазона имен, затем передайте эту коллекцию в ChartSeriesCollection::add. Параметр skipHiddenCells управляет тем, включать ли скрытые ячейки: true — исключает их, false — включает. В этом примере используется false, чтобы включить каждую ячейку в диапазон имен.
Следующий пример создает презентацию с одной серией и двумя точками данных. Ячейки B1:C1 предоставляют только имя серии; A2:A3 — метки категорий, а B2:B3 — числовые значения.
use aspose\slides\ChartType;
use aspose\slides\Presentation;
use aspose\slides\SaveFormat;
$presentation = new Presentation();
try {
$slide = $presentation->getSlides()->get_Item(0);
$chart = $slide->getShapes()->addChart(ChartType::ClusteredColumn, 50, 50, 620, 180);
$chart->getChartData()->getSeries()->clear();
$chart->getChartData()->getCategories()->clear();
$chart->setLegend(true);
$workbook = $chart->getChartData()->getChartDataWorkbook();
$workbook->clear(0);
// Эти две ячейки задают имя серии.
$workbook->getCell(0, 0, 1, "Product A");
$workbook->getCell(0, 0, 2, "2026");
$nameCells = $workbook->getCellCollection('Sheet1!$B$1:$C$1', false);
$series = $chart->getChartData()->getSeries()->add($nameCells, ChartType::ClusteredColumn);
// Отдельные ячейки задают категории и числовые точки данных.
$northCategory = $workbook->getCell(0, 1, 0, "North");
$southCategory = $workbook->getCell(0, 2, 0, "South");
$chart->getChartData()->getCategories()->add($northCategory);
$chart->getChartData()->getCategories()->add($southCategory);
$northValue = $workbook->getCell(0, 1, 1, 120);
$southValue = $workbook->getCell(0, 2, 1, 150);
$series->getDataPoints()->addDataPointForBarSeries($northValue);
$series->getDataPoints()->addDataPointForBarSeries($southValue);
$presentation->save("composite_series_name.pptx", SaveFormat::Pptx);
} finally {
$presentation->dispose();
}
В результате имя серии будет Product A 2026 с пробелом между значениями из двух ячеек. Легенда отображает это как одну запись для обоих столбцов. Ниже изображение, иллюстрирующее результат:
Получить автоматический цвет заливки серии
ChartSeries.getAutomaticSeriesColor возвращает цвет, вычисленный из индекса серии и стиля диаграммы. Это цвет, используемый, когда заливка серии не определена явно. Вызов метода читает вычисленный цвет; он не задаёт новую заливку.
Следующий пример выводит автоматический цвет каждой серии по умолчанию:
$firstSlideIndex = 0;
$presentation = new Presentation();
try {
$slide = $presentation->getSlides()->get_Item($firstSlideIndex);
$chart = $slide->getShapes()->addChart(ChartType::ClusteredColumn, 20, 20, 500, 200);
$seriesCount = java_values($chart->getChartData()->getSeries()->size());
for ($seriesIndex = 0; $seriesIndex < $seriesCount; $seriesIndex++) {
$series = $chart->getChartData()->getSeries()->get_Item($seriesIndex);
$automaticColor = $series->getAutomaticSeriesColor();
$red = java_values($automaticColor->getRed());
$green = java_values($automaticColor->getGreen());
$blue = java_values($automaticColor->getBlue());
echo "Series " . $seriesIndex . ": java.awt.Color[r=" . $red . ",g=" . $green . ",b=" . $blue . "]" . PHP_EOL;
}
} finally {
if (!java_is_null($presentation)) {
$presentation->dispose();
}
}
Пример вывода для стиля диаграммы по умолчанию:
Series 0: java.awt.Color[r=79,g=129,b=189]
Series 1: java.awt.Color[r=192,g=80,b=77]
Series 2: java.awt.Color[r=155,g=187,b=89]
Точные цвета зависят от стиля диаграммы и темы.
Установить инвертировать цвет заливки для серии диаграммы
Для серий типа столбец, колонка и пузырёк ChartSeries.setInvertIfNegative может отображать отрицательные значения другой заливкой. Установите обычную заливку серии сплошной, включите инверсию и задайте цвет для отрицательных значений через ChartSeries.getInvertedSolidFillColor. Отрицательные числа остаются без изменения в рабочей книге; меняется только их цвет отображения.
Следующий пример заменяет данные диаграммы по умолчанию одной серией. Строка 0 листа содержит имя серии, столбец 0 — имена категорий, а столбец 1 — значения:
$firstSlideIndex = 0;
$worksheetIndex = 0;
$headerRowIndex = 0;
$categoryColumnIndex = 0;
$firstSeriesColumnIndex = 1;
$firstDataRowIndex = 1;
$categoryNames = ["Category 1", "Category 2", "Category 3"];
$seriesValues = [-20, 50, -30];
$redColor = java("java.awt.Color")->RED;
$presentation = new Presentation();
try {
$slide = $presentation->getSlides()->get_Item($firstSlideIndex);
$chart = $slide->getShapes()->addChart(ChartType::ClusteredColumn, 20, 20, 500, 200);
$chartData = $chart->getChartData();
$workbook = $chartData->getChartDataWorkbook();
$chartData->getSeries()->clear();
$chartData->getCategories()->clear();
$seriesNameCell = $workbook->getCell($worksheetIndex, $headerRowIndex, $firstSeriesColumnIndex, "Series 1");
$chartType = $chart->getType();
$series = $chartData->getSeries()->add($seriesNameCell, $chartType);
$categoryCount = count($categoryNames);
for ($categoryIndex = 0; $categoryIndex < $categoryCount; $categoryIndex++) {
$dataRowIndex = $firstDataRowIndex + $categoryIndex;
$categoryName = $categoryNames[$categoryIndex];
$seriesValue = $seriesValues[$categoryIndex];
$categoryCell = $workbook->getCell($worksheetIndex, $dataRowIndex, $categoryColumnIndex, $categoryName);
$chartData->getCategories()->add($categoryCell);
$valueCell = $workbook->getCell($worksheetIndex, $dataRowIndex, $firstSeriesColumnIndex, $seriesValue);
$series->getDataPoints()->addDataPointForBarSeries($valueCell);
}
$automaticSeriesColor = $series->getAutomaticSeriesColor();
$series->getFormat()->getFill()->setFillType(FillType::Solid);
$series->getFormat()->getFill()->getSolidFillColor()->setColor($automaticSeriesColor);
$series->setInvertIfNegative(true);
$series->getInvertedSolidFillColor()->setColor($redColor);
$presentation->save("inverted_solid_fill_color.pptx", SaveFormat::Pptx);
} finally {
if (!java_is_null($presentation)) {
$presentation->dispose();
}
}
Результат:
Вы можете включить инверсию для одной точки через ChartDataPoint.setInvertIfNegative. В следующем примере инверсия отключена для серии и включена только для выбранной точки. Точке также присвоено отрицательное значение, чтобы эффект был виден:
$firstSlideIndex = 0;
$firstSeriesIndex = 0;
$targetDataPointIndex = 2;
$negativeValue = -30;
$redColor = java("java.awt.Color")->RED;
$presentation = new Presentation();
try {
$slide = $presentation->getSlides()->get_Item($firstSlideIndex);
$chart = $slide->getShapes()->addChart(ChartType::ClusteredColumn, 20, 20, 500, 200);
$series = $chart->getChartData()->getSeries()->get_Item($firstSeriesIndex);
$automaticSeriesColor = $series->getAutomaticSeriesColor();
$series->getFormat()->getFill()->setFillType(FillType::Solid);
$series->getFormat()->getFill()->getSolidFillColor()->setColor($automaticSeriesColor);
$series->getInvertedSolidFillColor()->setColor($redColor);
$series->setInvertIfNegative(false);
$dataPoint = $series->getDataPoints()->get_Item($targetDataPointIndex);
$dataPoint->getValue()->getAsCell()->setValue($negativeValue);
$dataPoint->setInvertIfNegative(true);
$presentation->save("data_point_invert_color_if_negative.pptx", SaveFormat::Pptx);
} finally {
if (!java_is_null($presentation)) {
$presentation->dispose();
}
}
Очистить конкретное значение точки данных
Чтобы сделать одну точку пустой, не удаляя остальные точки, установите её ячейку в рабочей книге в null. Для столбчатой диаграммы отображаемое значение доступно через ChartDataPoint.getValue. Точка остаётся в той же позиции категории, но диаграмма рассматривает её значение как пустое в соответствии с настройками отображения пустых значений.
Следующий пример очищает только вторую точку в первой серии:
$firstSlideIndex = 0;
$firstSeriesIndex = 0;
$targetDataPointIndex = 1;
$presentation = new Presentation();
try {
$slide = $presentation->getSlides()->get_Item($firstSlideIndex);
$chart = $slide->getShapes()->addChart(ChartType::ClusteredColumn, 20, 20, 500, 200);
$series = $chart->getChartData()->getSeries()->get_Item($firstSeriesIndex);
$dataPoint = $series->getDataPoints()->get_Item($targetDataPointIndex);
$dataPoint->getValue()->getAsCell()->setValue(null);
$presentation->save("clear_data_point_value.pptx", SaveFormat::Pptx);
} finally {
if (!java_is_null($presentation)) {
$presentation->dispose();
}
}
Точечные диаграммы используют отдельные ячейки X и Y, а пузырёчные диаграммы также используют ячейку размера. Очищайте только ту ячейку, которая представляет значение, которое вы хотите удалить. Не вызывайте ChartDataPointCollection.clear, когда нужно сохранить остальные точки, так как этот метод удаляет все точки данных из коллекции.
Управление отображением пустых ячеек
Скрытые ячейки, содержащие значения, отличаются от пустых ячеек. Чтобы включать или исключать данные из скрытых строк и столбцов листа, см. Include Data from Hidden Rows and Columns.
Пустая ячейка рабочей книги представляет отсутствующие данные; ячейка, содержащая 0, представляет известное числовое значение. Вызовите ChartDataCell::setValue с null, чтобы сделать ячейку пустой. Числовой ноль остаётся нулём независимо от настройки пустой ячейки.
Используйте Chart::setDisplayBlanksAs, чтобы выбрать способ отображения пустых ячеек в диаграмме. Эта настройка применяется к всей диаграмме. Она изменяет способ построения пустот, не заполняя пустую ячейку рабочей книги нулём или интерполированным значением.
Следующий автономный пример создает линейную диаграмму с одной серией, очищает значение для Дня 3 и сохраняет одну и ту же диаграмму в каждом режиме. Входной файл не требуется. ChartDataWorkbook использует лист 0, столбец 0 для меток категорий и столбец 1 для значений; строка 0 содержит имя серии. Итоговые данные: 10, 20, empty, 30, 40.
use aspose\slides\ChartType;
use aspose\slides\DisplayBlanksAsType;
use aspose\slides\Presentation;
use aspose\slides\SaveFormat;
$presentation = new Presentation();
try {
$slide = $presentation->getSlides()->get_Item(0);
$chart = $slide->getShapes()->addChart(ChartType::LineWithMarkers, 40, 40, 640, 400);
$chartData = $chart->getChartData();
$workbook = $chartData->getChartDataWorkbook();
$chartData->getSeries()->clear();
$chartData->getCategories()->clear();
$seriesNameCell = $workbook->getCell(0, 0, 1, "Measurements");
$series = $chartData->getSeries()->add($seriesNameCell, $chart->getType());
$values = [10, 20, 25, 30, 40];
for ($i = 0; $i < count($values); $i++) {
$categoryCell = $workbook->getCell(0, $i + 1, 0, "Day " . ($i + 1));
$chartData->getCategories()->add($categoryCell);
$valueCell = $workbook->getCell(0, $i + 1, 1, $values[$i]);
$series->getDataPoints()->addDataPointForLineSeries($valueCell);
}
// Оставить День 3 действительно пустым, сохранив его категорию и точку данных.
$workbook->getCell(0, 3, 1)->setValue(null);
$modes = [DisplayBlanksAsType::Gap, DisplayBlanksAsType::Zero, DisplayBlanksAsType::Span];
$modeNames = ["Gap", "Zero", "Span"];
for ($i = 0; $i < count($modes); $i++) {
$chart->setDisplayBlanksAs($modes[$i]);
$presentation->save("empty_cells_" . $modeNames[$i] . ".pptx", SaveFormat::Pptx);
}
} finally {
$presentation->dispose();
}
Каждый выходной файл сохраняет режим, назначенный перед сохранением: empty_cells_Gap.pptx, empty_cells_Zero.pptx и empty_cells_Span.pptx. Чтобы сохранить только одну версию, задайте нужный режим и сохраните презентацию один раз, вместо перебора режимов.
Сравнение ниже показывает одинаковые данные во всех трех файлах. День 3 пуст в рабочей книге во всех случаях:
Видимый эффект зависит от типа диаграммы. Линейная диаграмма позволяет легко сравнивать все три режима. В столбчатых и колонных диаграммах нет линии для соединения через отсутствующую категорию, поэтому Span не может создать показанный выше соединительный сегмент; отсутствующий столбец и столбец нулевой высоты могут выглядеть одинаково. Аналогично, точечная диаграмма только с маркерами не имеет соединительной линии. Не ожидайте три разных результата для каждого типа диаграммы; проверьте вывод для используемого типа.
Установить ширину промежутка серии
Ширина промежутка — это пространство между соседними кластерами столбцов или колонн, выраженное в процентах от ширины столбца или колонны. Как и перекрытие, она относится к родительской группе серий, а не к отдельной серии. Вызовите ChartSeriesGroup.setGapWidth один раз для группы. Большое значение создаёт больше пространства между кластерами; меньшего — делает их плотнее.
Следующий пример изменяет ширину промежутка и сохраняет только конечную презентацию:
$firstSlideIndex = 0;
$firstSeriesIndex = 0;
$gapWidthPercent = 30;
$presentation = new Presentation();
try {
$slide = $presentation->getSlides()->get_Item($firstSlideIndex);
$chart = $slide->getShapes()->addChart(ChartType::StackedColumn, 20, 20, 500, 200);
$series = $chart->getChartData()->getSeries()->get_Item($firstSeriesIndex);
$series->getParentSeriesGroup()->setGapWidth($gapWidthPercent);
$presentation->save("gap_width_30.pptx", SaveFormat::Pptx);
} finally {
if (!java_is_null($presentation)) {
$presentation->dispose();
}
}
Результат:
Часто задаваемые вопросы
Какие типы диаграмм поддерживают серии данных?
Все типы диаграмм, представленные перечислением ChartType, используют данные диаграммы, но их серии не всегда имеют одинаковую структуру значений или настройки. Например, категориальные диаграммы используют категории и значения, точечные диаграммы используют значения X и Y, а пузырёчные добавляют размеры пузырей. Используйте метод создания точек данных, соответствующий типу серии. Параметры, такие как перекрытие и ширина промежутка, применимы только к совместимым группам столбцов или колонн.
Что такое группа серий диаграммы?
ChartSeriesGroup содержит совместимые серии, которые разделяют настройки построения уровня группы. Комбинированная диаграмма может содержать более одной группы, поэтому изменение группы, полученной через одну серию, не обязательно изменит все серии в диаграмме.
Содержит ли вновь созданная диаграмма данные по умолчанию?
Да. По умолчанию ShapeCollection.addChart создаёт примерные серии, категории и значения. Вы можете редактировать эти ячейки или очистить обе коллекции серий и категорий перед добавлением полностью пользовательского набора данных. Перегрузка также может создавать диаграмму без данных по умолчанию.
Как объекты диаграммы связаны с ячейками рабочей книги?
Имена серий, метки категорий и значения точек данных ссылаются на ячейки в ChartDataWorkbook. Изменение ссылки ячейки обновляет соответствующий элемент диаграммы. При построении пользовательских данных сохраняйте выравнивание строк категорий и строк значений серий, чтобы каждая точка отображалась под нужной категорией.
Как очистить одну точку вместо всей серии?
Установите соответствующую ячейку значения в null, чтобы сохранить позицию категории точки как пустой. Используйте ChartDataPointCollection.clear только когда хотите удалить все точки из этой серии. Если вы также удаляете категории, обновите каждую серию, чтобы их значения оставались согласованными с коллекцией категорий.
Как отображаются пустые точки?
Результат зависит от типа диаграммы и значения, настроенного через Chart.setDisplayBlanksAs. Поддерживаемые диаграммы могут отображать пустоты как промежутки, как нулевые значения или соединяя соседние точки. Выберите настройку, соответствующую смыслу пропущенных данных в вашей презентации. См. Control the Display of Empty Cells для полного примера и визуального сравнения.
Как форматируются отрицательные значения?
Для поддерживаемых серий типа столбец, колонка и пузырёк вызовите ChartSeries.setInvertIfNegative и задайте цвет, возвращаемый ChartSeries.getInvertedSolidFillColor. Вы можете переопределить поведение для отдельной точки с помощью ChartDataPoint.setInvertIfNegative. Эти методы влияют на форматирование, а не на сохранённые числовые значения.
Какой формат имеет приоритет, когда и серия, и точка отформатированы?
Явное форматирование отдельной точки имеет приоритет для этой точки. Другие точки продолжают использовать явный формат серии или, если формат серии не определён, автоматический стиль и тему диаграммы. Настройки группы, такие как перекрытие и ширина промежутка, управляют расположением и не являются переопределением форматирования уровня точки.
Есть ли ограничение на количество серий в диаграмме?
Aspose.Slides не накладывает отдельного фиксированного ограничения на количество серий. На практике ограничения файлов презентаций, доступная память, время рендеринга и читаемость диаграммы определяют полезный лимит.
Что изменить, когда столбцы слишком близко или слишком далеко друг от друга?
Вызовите ChartSeriesGroup.setGapWidth для соответствующей родительской группы серий. Увеличьте значение, чтобы расширить пространство между кластерами, или уменьшите его, чтобы собрать кластеры ближе друг к другу.