Камера Excel в Aspose.Cells for Node.js via C++

Камера Excel — это объект рабочего листа, который отображает актуальное изображение диапазона ячеек и располагается на слое рисования как обычное изображение. Aspose.Cells поддерживает два режима создания: динамическое изображение, которое автоматически обновляется при изменении исходных данных, и статическое изображение, фиксирующее однократный снимок диапазона. В этой статье рассматриваются оба подхода, чтобы вы могли выбрать тот, который подходит для вашей компоновки.

Что такое камера Excel?

Камера Excel по сути представляет собой графический объект, закреплённый в определённой строке и столбце на слое рисования рабочего листа. В отличие от обычного вставленного изображения, камера связана с исходным диапазоном через формулу в стиле A1, например "A1:F10". При изменении любой ячейки в этом диапазоне изображение камеры автоматически обновляется, отражая новое содержимое. Камера сохраняет всё форматирование исходной области — границы, цвета фона, шрифты и числовые форматы, — поэтому всё видимое содержимое ячеек воспроизводится и в изображении камеры. Это делает камеру особенно полезной для информационных панелей, сводок, боковых панелей и макетов отчётов, где требуется предварительный просмотр другой области без прокрутки или дублирования данных. Следует учитывать два момента: необходимо вызвать updateSelectedValue() перед сохранением книги, а файл экспортируется в HTML или PDF, поскольку эти форматы используют встроенные данные изображения, а не пересчёт в режиме реального времени.

Метод 1 — Добавление динамического изображения камеры

Динамическая камера — наиболее распространённый подход, максимально близкий к встроенному инструменту «Камера» в Excel. Она создаётся путём добавления изображения без начального содержимого и присвоения ему свойства Formula, ссылающегося на исходный диапазон. После присвоения формулы вызов updateSelectedValue() обновляет встроенное изображение, синхронизируя его с отображаемыми ячейками. Камера реализована не с помощью отдельного класса — она полностью основана на стандартном типе Picture. Основные API:

• Pictures.add(int upperLeftRow, int upperLeftColumn, null) — добавляет изображение, закреплённое в указанной строке и столбце. Передача null в параметр stream создаёт пустое изображение, служащее заполнителем для динамической камеры. Метод возвращает индекс нового изображения.
• pictures.get(index) — возвращает указанный объект Picture из коллекции по индексу.
• Picture.formula — строковое свойство (get/set), содержащее ссылку в стиле A1 на исходный диапазон, отображаемый камерой, например "A1:F10".
• Picture.updateSelectedValue() — метод без возвращаемого значения, обновляющий встроенное изображение по данным ячеек, на которые ссылается formula.

updateSelectedValue() ДОЛЖЕН быть вызван перед сохранением в формате HTML или PDF; в противном случае экспортированный файл не будет содержать данные изображения, а при его отображении камера будет пустой.

Следующий код создаёт книгу, добавляет пустую картинку, привязанную к строке 10 столбцу 6, связывает её с исходным диапазоном A1:F10 через свойство Formula, обновляет встроенные данные изображения и сохраняет книгу.

const aspose = require("aspose.cells");
let workbook = new aspose.Workbook();
let worksheet = workbook.getWorksheets().get(0);
worksheet.setName("CameraDemo");
// Динамическая камера: добавить пустое изображение, связать его через формулу с A1:F10, затем обновить
let pictures = worksheet.getPictures();
let index = pictures.add(10, 6, null);
pictures.get(index).setFormula("A1:F10");
pictures.get(index).updateSelectedValue();
workbook.save("output_dynamic.xlsx", aspose.SaveFormat.Xlsx);

Метод 2 — Добавление статического изображения камеры

Статическая камера — это однократно отрисованное изображение диапазона ячеек. Вместо поддержания динамической связи диапазон однократно преобразуется в массив байтов изображения, который помещается в Buffer и добавляется как обычное изображение. Содержимое изображения фиксируется в момент создания и не обновляется автоматически при изменении исходных ячеек. Основные API:

• Cells.createRange(address) — создаёт объект Range на основе адреса в стиле A1, например "A1:F10".
• Range.toImage(ImageOrPrintOptions options) — преобразует диапазон в массив байтов изображения. Передача null использует параметры рендеринга по умолчанию; существуют перегрузки для более детального контроля вывода.
• new Buffer(byte[] buffer) — помещает байты отрендерированного изображения в Buffer, который можно передать в getPictures().add.
• Pictures.add(int upperLeftRow, int upperLeftColumn, null) — добавляет изображение, закреплённое в указанной строке и столбце; в этом случае в метод передаётся Buffer, полученный при рендеринге. Следующий код создаёт книгу, формирует Range для A1:F10, преобразует его в байты изображения с помощью range.toImage(null), помещает байты в Buffer, добавляет изображение, привязанное к строке 10 столбцу 6, и сохраняет книгу.

const aspose = require("aspose.cells");
const { MemoryStream } = require("aspose.cells");
let workbook = new aspose.Workbook();
let worksheet = workbook.getWorksheets().get(0);
worksheet.setName("CameraDemo");
// Статичная камера: построить диапазон, преобразовать в байты, обернуть в MemoryStream, добавить как изображение
let range = worksheet.getCells().createRange("A1:F10");
let imageBytes = range.toImage(null);
let stream = new MemoryStream();
stream.write(imageBytes);
let pictures = worksheet.getPictures();
pictures.add(10, 6, stream);
workbook.save("output_static.xlsx", aspose.SaveFormat.Xlsx);

Выбор между динамическим и статическим режимом

• Динамическая камера: обновляется при каждом пересчёте, поддерживает экспорт в HTML и PDF после вызова updateSelectedValue() и сохраняет динамическую связь на протяжении всего срока существования файла.
• Статическая камера: однократная отрисовка, которая никогда не обновляется; этот вариант полезен, если во время сборки в файл необходимо встроить фиксированный визуальный снимок, а не динамическое отображение данных. Aspose.Cells поддерживает как динамическую автоматически обновляемую камеру, построенную на Picture.formula и updateSelectedValue(), так и статическую камеру для однократной отрисовки, созданную с помощью Range.toImage и Buffer. Выбирайте динамический подход, если результат должен оставаться синхронизированным с исходными ячейками, а статический — если требуется лишь получить фиксированный визуальный снимок во время сборки.