Обновление сводных таблиц и кэшей сводных таблиц в Aspose.Cells for Node.js via Java

Aspose.Cells предоставляет многоуровневый API обновления, который позволяет перезагружать данные сводных таблиц на четырёх различных уровнях — от всей рабочей книги до отдельной сводной таблицы. Начиная с версии Aspose.Cells for Node.js via Java v26.7, устаревший метод PivotTable.RefreshData() помечен как нерекомендуемый и должен быть заменён более эффективными, учитывающими кэширование API, описанными в этой статье.

Введение

Обновление сводной таблицы редко бывает одной операцией. За кулисами Aspose.Cells поддерживает многоуровневую цепочку данных, которая соединяет исходные данные с отображаемыми значениями на рабочем листе. Понимание этой цепочки является ключом к выбору правильного API обновления в любой ситуации. Четырёхуровневая цепочка данных выглядит так:

Источник данных — исходные диапазоны рабочего листа, запрос к базе данных или диапазон консолидации, где хранятся необработанные значения.
PivotCache — снимок исходных данных в памяти. Каждая сводная таблица построена поверх PivotCache; именно здесь все данные собираются и агрегируются.
PivotTable — объект представления, определяющий поля строк, столбцов, значений и фильтров. PivotTable считывает данные только из своего PivotCache, никогда напрямую из источника данных.
Cells — ячейки Cells рабочего листа, в которые PivotTable вычисляет и отображает свои значения и стили.

PivotCache.SourceType (перечисление PivotTableSourceType) указывает, откуда поступили данные кэша. Начиная с версии v26.7, PivotCache.Refresh() поддерживает только типы источников Sheet и Consolidation — то есть данные, которые находятся в диапазонах рабочего листа. Внешние источники (базы данных, внешние подключения и т.д.) пока не могут быть обновлены через API кэша.

Из-за этой цепочки в Aspose.Cells существуют два основных пути обновления:

PivotTable.CalculateData() — пересчитывает отображение одной PivotTable из уже кэшированных данных, без обращения к источнику данных. Все сценарии в этой статье используют исходные данные из ячеек рабочего листа, поэтому тип источника — Sheet, и операции обновления работают так, как описано.

Быстрый старт

Если вам нужен только минимально возможный код для обновления всех сводных таблиц в рабочей книге, достаточно одного вызова:

const aspose = require('aspose.cells');
const workbook = new aspose.cells.Workbook("input.xlsx");
workbook.refreshAll();
workbook.save("output.xlsx");

Всё остальное в этой статье объясняет, когда вместо этого выбрать более узкий API.

Необходимые импорты

const aspose = require('aspose.cells');
Или для конкретных импортов: const { Workbook, Cells, PivotTableSourceType } = require('aspose.cells');

Обновление всех сводных таблиц в рабочей книге

Если вам нужно убедиться, что каждый кэш сводных таблиц и каждая сводная таблица в рабочей книге отражают самые последние исходные данные, самый простой и всеобъемлющий API — это Workbook.RefreshAll(). Один вызов обходит всю рабочую книгу — обновляя каждый PivotCache из его источника, а затем пересчитывая каждую зависимую PivotTable. Это рекомендуемый подход для общих полных обновлений документа, когда производительность не является проблемой. Следующий пример создаёт рабочую книгу с исходным диапазоном Fruit/Year/Amount, создаёт одну сводную таблицу, изменяет некоторые исходные значения, а затем использует RefreshAll() для актуализации всего за один вызов.

const AsposeCells = require("aspose.cells");
// Create a new workbook
const workbook = new AsposeCells.Workbook();
const worksheet = workbook.getWorksheets().get(0);
// Write header row into cells A1:C1
worksheet.getCells().get("A1").putValue("Fruit");
worksheet.getCells().get("B1").putValue("Year");
worksheet.getCells().get("C1").putValue("Amount");
// Write data rows into cells A2:C9 (8 rows of fruit data across 2020 and 2021)
worksheet.getCells().get("A2").putValue("grape");
worksheet.getCells().get("B2").putValue(2020);
worksheet.getCells().get("C2").putValue(50);
worksheet.getCells().get("A3").putValue("blueberry");
worksheet.getCells().get("B3").putValue(2020);
worksheet.getCells().get("C3").putValue(60);
worksheet.getCells().get("A4").putValue("kiwi");
worksheet.getCells().get("B4").putValue(2020);
worksheet.getCells().get("C4").putValue(70);
worksheet.getCells().get("A5").putValue("cherry");
worksheet.getCells().get("B5").putValue(2020);
worksheet.getCells().get("C5").putValue(80);
worksheet.getCells().get("A6").putValue("grape");
worksheet.getCells().get("B6").putValue(2021);
worksheet.getCells().get("C6").putValue(90);
worksheet.getCells().get("A7").putValue("blueberry");
worksheet.getCells().get("B7").putValue(2021);
worksheet.getCells().get("C7").putValue(100);
worksheet.getCells().get("A8").putValue("kiwi");
worksheet.getCells().get("B8").putValue(2021);
worksheet.getCells().get("C8").putValue(110);
worksheet.getCells().get("A9").putValue("cherry");
worksheet.getCells().get("B9").putValue(2021);
worksheet.getCells().get("C9").putValue(120);
// Add a pivot table: source range "A1:C9", destination cell "E3", name "Pivot1"
const pivotIndex = worksheet.getPivotTables().add("A1:C9", "E3", "Pivot1");
const pivotTable = worksheet.getPivotTables().get(pivotIndex);
// Assign pivot fields: Fruit to Rows, Year to Columns, Amount to Data
pivotTable.addFieldToArea(AsposeCells.PivotFieldType.Row, "Fruit");
pivotTable.addFieldToArea(AsposeCells.PivotFieldType.Column, "Year");
pivotTable.addFieldToArea(AsposeCells.PivotFieldType.Data, "Amount");
// Modify several Amount values in the source data to simulate changes
worksheet.getCells().get("C2").putValue(55);
worksheet.getCells().get("C5").putValue(85);
worksheet.getCells().get("C9").putValue(125);
// Refresh every pivot table / pivot cache in the workbook
workbook.refreshAll();
// Save the workbook
workbook.save("output.xlsx");

Обновление всех сводных таблиц на одном рабочем листе

Иногда вам нужно обновить только сводные таблицы, которые находятся на одном конкретном рабочем листе — например, когда известно, что сводные таблицы на других листах не связаны и не должны быть затронуты. Для этого случая Aspose.Cells предоставляет Worksheet.RefreshPivotTables(), который ограничен одним экземпляром Worksheet.

let workbook = new AsposeCells.Workbook();
let worksheet = workbook.getWorksheets().get(0);
worksheet.getCells().get("A1").putValue("Fruit");
worksheet.getCells().get("B1").putValue("Year");
worksheet.getCells().get("C1").putValue("Amount");
worksheet.getCells().get("A2").putValue("grape");
worksheet.getCells().get("B2").putValue(2020);
worksheet.getCells().get("C2").putValue(100);
worksheet.getCells().get("A3").putValue("blueberry");
worksheet.getCells().get("B3").putValue(2021);
worksheet.getCells().get("C3").putValue(150);
worksheet.getCells().get("A4").putValue("kiwi");
worksheet.getCells().get("B4").putValue(2020);
worksheet.getCells().get("C4").putValue(200);
worksheet.getCells().get("A5").putValue("cherry");
worksheet.getCells().get("B5").putValue(2021);
worksheet.getCells().get("C5").putValue(120);
worksheet.getCells().get("A6").putValue("grape");
worksheet.getCells().get("B6").putValue(2021);
worksheet.getCells().get("C6").putValue(180);
worksheet.getCells().get("A7").putValue("blueberry");
worksheet.getCells().get("B7").putValue(2020);
worksheet.getCells().get("C7").putValue(130);
worksheet.getCells().get("A8").putValue("kiwi");
worksheet.getCells().get("B8").putValue(2021);
worksheet.getCells().get("C8").putValue(220);
worksheet.getCells().get("A9").putValue("cherry");
worksheet.getCells().get("B9").putValue(2020);
worksheet.getCells().get("C9").putValue(140);
let pivotIndex = worksheet.getPivotTables().add("A1:C9", "E3", "Pivot1");
let pivotTable = worksheet.getPivotTables().get(pivotIndex);
pivotTable.addFieldToArea(AsposeCells.PivotFieldType.Row, "Fruit");
pivotTable.addFieldToArea(AsposeCells.PivotFieldType.Column, "Year");
pivotTable.addFieldToArea(AsposeCells.PivotFieldType.Data, "Amount");
worksheet.getCells().get("C2").putValue(300);
worksheet.getCells().get("C5").putValue(250);
worksheet.getCells().get("C9").putValue(400);
worksheet.refreshPivotTables();
workbook.save("output.xlsx");

Обновление одной сводной таблицы

Если вы хотите точно контролировать одну сводную таблицу, кэш-ориентированный API предоставляет два варианта. Выбор между ними зависит от того, что именно изменилось: базовые исходные данные или только параметры представления/макета самой сводной таблицы.

Исходные данные изменились — используйте `PivotCache.Refresh()`

Если базовые исходные данные изменились, правильной точкой входа является pivotTable.PivotCache.Refresh(). Этот вызов перечитывает исходные данные в кэш, а затем пересчитывает каждую PivotTable, зависящую от этого кэша.

Изменились только представление/макет — используйте `CalculateData()`

Если исходные данные не изменились, но изменились только параметры представления или макета сводной таблицы (например, поле было перемещено в другую область или переключена настройка обновления при открытии), нет необходимости обращаться к источнику данных. Кэш уже содержит правильные данные; необходимо только пересчитать отображаемую PivotTable. В этом случае pivotTable.CalculateData() является правильным выбором. Следующий пример изменяет не исходное свойство сводной таблицы, а затем вызывает CalculateData() для её повторного отображения из существующего кэша.

var workbook = new AsposeCells.Workbook();
var worksheet = workbook.getWorksheets().get(0);
// Write Fruit / Year / Amount header row
worksheet.getCells().get("A1").putValue("Fruit");
worksheet.getCells().get("B1").putValue("Year");
worksheet.getCells().get("C1").putValue("Amount");
// Write 8 data rows (rows 2-9, fitting the source range A1:C9)
worksheet.getCells().get("A2").putValue("Grape");
worksheet.getCells().get("B2").putValue(2020);
worksheet.getCells().get("C2").putValue(100);
worksheet.getCells().get("A3").putValue("Blueberry");
worksheet.getCells().get("B3").putValue(2020);
worksheet.getCells().get("C3").putValue(200);
worksheet.getCells().get("A4").putValue("Kiwi");
worksheet.getCells().get("B4").putValue(2020);
worksheet.getCells().get("C4").putValue(300);
worksheet.getCells().get("A5").putValue("Cherry");
worksheet.getCells().get("B5").putValue(2020);
worksheet.getCells().get("C5").putValue(400);
worksheet.getCells().get("A6").putValue("Grape");
worksheet.getCells().get("B6").putValue(2021);
worksheet.getCells().get("C6").putValue(150);
worksheet.getCells().get("A7").putValue("Blueberry");
worksheet.getCells().get("B7").putValue(2021);
worksheet.getCells().get("C7").putValue(250);
worksheet.getCells().get("A8").putValue("Kiwi");
worksheet.getCells().get("B8").putValue(2021);
worksheet.getCells().get("C8").putValue(350);
worksheet.getCells().get("A9").putValue("Cherry");
worksheet.getCells().get("B9").putValue(2021);
worksheet.getCells().get("C9").putValue(450);
// Add a pivot table named "Pivot1" placed at destination cell E3, sourcing from A1:C9
var pivotIndex = worksheet.getPivotTables().add("A1:C9", "E3", "Pivot1");
var pivotTable = worksheet.getPivotTables().get(pivotIndex);
// Assign fields: Fruit to Row, Year to Column, Amount to Data
pivotTable.addFieldToArea(AsposeCells.PivotFieldType.Row, "Fruit");
pivotTable.addFieldToArea(AsposeCells.PivotFieldType.Column, "Year");
pivotTable.addFieldToArea(AsposeCells.PivotFieldType.Data, "Amount");
// Modify a view/layout property — this is a presentation-only change,
// so it does NOT require re-reading the source data through PivotCache.Refresh().
pivotTable.setRefreshDataOnOpeningFile(false);
// CalculateData() re-renders THIS pivot table's display (data + style) from the
// data already held in the PivotCache. Because the source data did not change,
// no round-trip to the source is performed — only the cached values are recalculated
// into worksheet cells.
pivotTable.calculateData();
// Save the workbook to disk
workbook.save("output.xlsx");

Рабочая книга часто содержит множество сводных таблиц, которые все расположены поверх одного общего кэша. Чтобы перечислить их — например, перед выполнением пакетного обновления или для диагностики влияния общего кэша — используйте PivotCache.GetPivotTables(). Этот метод возвращает коллекцию всех PivotTable, зависящих от данного кэша.

Миграция с устаревшего `PivotTable.RefreshData()`

До версии Aspose.Cells for Node.js via Java v26.7 стандартным способом обновления сводной таблицы был вызов PivotTable.RefreshData() для каждой сводной таблицы отдельно. Начиная с версии v26.7 этот метод помечен как устаревший и должен быть заменён на кэш-ориентированные API, описанные выше. Есть две причины, почему подход RefreshData() для каждой таблицы проблематичен в реальных рабочих книгах:

Он повторно извлекает данные из источника при каждом вызове, даже если источник не изменился. Рекомендуемые замены: Следующий пример демонстрирует новый эффективный шаблон для рабочих книг с несколькими сводными таблицами, использующими один кэш.

Какой API обновления мне следует использовать?

В таблице ниже приведены доступные API обновления и рекомендации по выбору каждого из них.

Цель	Рекомендуемый API	Примечания
Обновить всё в рабочей книге	`Workbook.RefreshAll()`	Один вызов; охватывает все кэши и таблицы.
Обновить только сводные таблицы на одном листе	`Worksheet.RefreshPivotTables()`	Ограничено одним рабочим листом.
Исходные данные изменились для одного кэша	`pivotTable.PivotCache.Refresh()`	Обновляет ВСЕ сводные таблицы на этом общем кэше.
Изменились только параметры представления/макета	`pivotTable.CalculateData()`	Пропускает ненужное обращение к источнику.
Получить список всех сводных таблиц на общем кэше	`pivotCache.GetPivotTables()`	Используйте для перечисления перед массовым обновлением.
На практике отдавайте предпочтение кэш-ориентированным API вместо устаревшего потабличного `RefreshData()`. Они учитывают общие кэши, избегают избыточных обращений к источнику и позволяют выбрать наименьший объём, удовлетворяющий вашим требованиям к обновлению.

Распространённые ошибки

Забыли обновить перед сохранением. Сводная таблица записывает свои отображаемые значения на рабочий лист только при обновлении цепочки данных. Если вы изменяете исходные ячейки, вызовите PivotCache.Refresh() (или Workbook.RefreshAll()) перед Workbook.save(), иначе сохранённый файл всё ещё будет содержать старые агрегированные значения.
Вызов устаревшего RefreshData() для каждой таблицы. В версии v26.7 метод PivotTable.RefreshData() помечен как устаревший и повторно извлекает данные из источника при каждом вызове. При наличии нескольких сводных таблиц, использующих общий кэш, это означает N избыточных обращений к источнику. Замените его одним вызовом PivotCache.Refresh(), за которым следует CalculateData() для каждой таблицы.
Обновление, когда изменился только макет. Если вы изменили только представление сводной таблицы (порядок столбцов, ConsolidationFunction и т.д.), не затрагивая исходные данные, вызов PivotCache.Refresh() не нужен и медленный. Вызовите pivotTable.CalculateData() для повторного отображения из существующего кэша.
Внешний источник не поддерживается PivotCache.Refresh(). Если источник сводной таблицы поступает из внешнего подключения (база данных, OLAP-куб и т.д.), PivotCache.Refresh() не может обновить его в версии v26.7 — в настоящее время он поддерживает только типы источников Sheet и Consolidation. Для внешних источников откройте рабочую книгу заново или пересоздайте кэш из источника.

Добавить поля строк и столбцов сводной таблицы в Aspose.Cells для .NET