Камера Excel в Aspose.Cells for Python via Java

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

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

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

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

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

  • PictureCollection.add(int upperLeftRow, int upperLeftColumn, input) — добавляет изображение, привязанное к указанной строке и столбцу. Передача None в параметр stream создаёт пустое изображение, выступающее в качестве заполнителя для динамической Камеры. Метод возвращает индекс нового изображения.
  • worksheet.getPictures().get(index) — метод доступа для получения определённого Picture из коллекции.
  • Picture.getFormula() / Picture.setFormula() — получение/установка ссылки в стиле A1 на исходный диапазон, который отражает Камера, например "A1:F10".
  • Picture.updateSelectedValue() — метод без возвращаемого значения, который обновляет внедрённые данные изображения из ячеек, на которые ссылается формула.

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

import jpype
import jpype.imports
from asposecells.api import Workbook, SaveFormat
workbook = Workbook()
worksheet = workbook.getWorksheets().get(0)
worksheet.setName("CameraDemo")
# Динамическая камера: добавить пустое изображение, связать его через формулу с A1:F10, затем обновить
pictures = worksheet.getPictures()
index = pictures.add(10, 6, None)
pictures.get(index).setFormula("A1:F10")
pictures.get(index).updateSelectedValue()
workbook.save("output_dynamic.xlsx", SaveFormat.XLSX)

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

Статическая Камера, по сути, представляет собой однократно отрисованный предварительный просмотр диапазона ячеек. Вместо поддержания динамической связи диапазон однократно отрисовывается в байты изображения, эти байты оборачиваются в byte[] массив и добавляются как обычное изображение. Содержимое изображения фиксируется в момент создания и не обновляется автоматически при изменении исходных ячеек. Ключевые API:

  • Cells.createRange(String address) — создаёт объект Range из адреса в стиле A1, например "A1:F10".
  • Range.toImage(ImageOrPrintOptions options) — отрисовывает диапазон в байты изображения. Передача None использует параметры отрисовки по умолчанию; существуют перегрузки для более точного управления выводом.
  • byte[] array(byte[] buffer) — оборачивает отрисованные байты изображения в byte[] массив, который можно передать в PictureCollection.add.
  • PictureCollection.add(int upperLeftRow, int upperLeftColumn, input) — добавляет изображение, привязанное к указанной строке и столбцу, на этот раз передавая byte[] массив, созданный при отрисовке. Следующий код создаёт рабочую книгу, формирует Range для A1:F10, отрисовывает его в байты изображения через Range.toImage(None), оборачивает байты в byte[] массив, добавляет изображение, привязанное к строке 10 и столбцу 6, и сохраняет рабочую книгу.
import jpype
import jpype.imports
from asposecells.api import Workbook, SaveFormat
workbook = Workbook()
worksheet = workbook.getWorksheets().get(0)
worksheet.setName("CameraDemo")
# Статическая камера: построить диапазон, отрисовать в байты, обернуть в ByteArrayInputStream, добавить как изображение
range_ = worksheet.getCells().createRange("A1:F10")
image_bytes = range_.toImage(None)
pictures = worksheet.getPictures()
pictures.add(10, 6, jpype.JArray(jpype.JByte)(image_bytes))
workbook.save("output_static.xlsx", SaveFormat.XLSX)

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

  • Динамическая Камера: обновляется при каждом пересчёте, поддерживает экспорт в HTML и PDF после вызова updateSelectedValue(), и сохраняет поведение динамической связи на протяжении всего срока жизни файла.
  • Статическая Камера: однократная отрисовка, которая никогда не обновляется, полезна, когда требуется фиксированный визуальный снимок, встроенный во время сборки, а не динамическое отражение данных. Aspose.Cells for Python via Java поддерживает как динамическую, автоматически обновляемую Камеру, построенную на setFormula плюс updateSelectedValue(), так и статическую Камеру однократной отрисовки, построенную на toImage плюс byte[] массив. Выбирайте динамический подход, когда выходной результат должен оставаться синхронизированным с исходными ячейками, и выбирайте статический подход, когда требуется только фиксированный визуальный снимок во время сборки.
Как экспортировать формулы Excel в другие форматы выражений