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

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

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

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

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

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

• Pictures.Add(int upperLeftRow, int upperLeftColumn, Vector<uint8_t> data) — добавляет изображение, привязанное к указанной строке и столбцу. Передача пустого Vector<uint8_t>() создаёт пустое изображение, выступающее заполнителем для динамической камеры. Метод возвращает индекс нового изображения.
• worksheet.GetPictures().Get(int index) — получает конкретное Picture из коллекции по индексу.
• Picture.SetFormula(U16String value) — задаёт ссылку в стиле A1 на исходный диапазон, который отражает камера, например U16String("A1:F10").
• Picture.UpdateSelectedValue() — обновляет встроенные данные изображения из ячеек, на которые ссылается Formula.

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

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

#include "Aspose.Cells.h"
using namespace Aspose::Cells;
int main()
{
    Aspose::Cells::Startup();
    Workbook workbook;
    Worksheet worksheet = workbook.GetWorksheets().Get(0);
    worksheet.SetName(U16String("CameraDemo"));
    // Динамическая камера: добавить пустое изображение, связать его через формулу с A1:F10, затем обновить
    int index = worksheet.GetPictures().Add(10, 6, Vector<uint8_t>());
    Picture picture = worksheet.GetPictures().Get(index);
    picture.SetFormula(U16String("A1:F10"));
    picture.UpdateSelectedValue();
    workbook.Save(U16String("output_dynamic.xlsx"), SaveFormat::Xlsx);
    Aspose::Cells::Cleanup();
    return 0;
}

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

Статическая камера по сути является однократно отрисованным предварительным просмотром диапазона ячеек. Вместо поддержки живой ссылки вы однократно отрисовываете диапазон в буфер байтов Vector<uint8_t> и передаёте этот буфер непосредственно в Pictures.Add(row, col, data). Содержимое изображения фиксируется в момент создания и не обновляется автоматически при изменении исходных ячеек. Ключевые API:

• Cells.CreateRange(U16String address) — создаёт объект Range по адресу в стиле A1, например U16String("A1:F10").
• Range.ToImage(ImageOrPrintOptions options) — отрисовывает диапазон в буфер байтов Vector<uint8_t>. Передача nullptr использует параметры отрисовки по умолчанию; существуют перегрузки для более тонкого управления выводом.
• Pictures.Add(int upperLeftRow, int upperLeftColumn, Vector<uint8_t> data) — добавляет изображение, привязанное к указанной строке и столбцу, в этот раз передавая буфер байтов, полученный из Range.ToImage. Следующий код создаёт рабочую книгу, формирует Range для A1:F10, отрисовывает его в байты изображения через Range.ToImage(nullptr), добавляет изображение, привязанное к строке 10 и столбцу 6, и сохраняет рабочую книгу.

#include "Aspose.Cells.h"
using namespace Aspose::Cells;
int main()
{
    Aspose::Cells::Startup();
    Workbook workbook;
    Worksheet worksheet = workbook.GetWorksheets().Get(0);
    worksheet.SetName(U16String("CameraDemo"));
    // Статичная камера: создать Range, отрендерить в байты, добавить как изображение
    Range range = worksheet.GetCells().CreateRange(U16String("A1:F10"));
    Vector<uint8_t> imageBytes = range.ToImage(nullptr);
    worksheet.GetPictures().Add(10, 6, imageBytes);
    workbook.Save(U16String("output_static.xlsx"), SaveFormat::Xlsx);
    Aspose::Cells::Cleanup();
    return 0;
}

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

• Динамическая камера: обновляется при каждом пересчёте, поддерживает экспорт в HTML и PDF после вызова UpdateSelectedValue() и сохраняет поведение живой ссылки на протяжении всего срока жизни файла.
• Статическая камера: однократная отрисовка, которая никогда не обновляется; полезна, когда требуется фиксированный визуальный снимок, встроенный во время сборки, а не живое отражение данных. Aspose.Cells поддерживает и динамическую, автоматически обновляемую камеру, построенную на основе Picture.Formula и UpdateSelectedValue(), и статическую, однократную камеру, построенную на основе Range.ToImage и Vector<uint8_t>. Выбирайте динамический подход, когда ваш вывод должен оставаться синхронизированным с исходными ячейками, и статический подход, когда вам нужен только фиксированный визуальный снимок во время сборки.