Вставка изображения в ячейку

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

Введение

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

• Подход 1 — Размещение плавающего изображения над ячейкой. Добавьте Picture на рабочий лист, установите его setPlacement в MOVE_AND_SIZE и настройте ячейки его привязки (setUpperLeftRow, setUpperLeftColumn, setLowerRightRow, setLowerRightColumn) так, чтобы изображение покрывало ровно одну ячейку.
• Подход 2 — Внедрение изображения непосредственно в ячейку. Присвойте байты изображения свойству ячейки setEmbeddedImage. Изображение автоматически масштабируется, чтобы соответствовать области отображения ячейки, и перемещается вместе с ячейкой. Остальная часть статьи рассматривает оба подхода, объясняет соответствующие API и показывает, как использовать их в коде.

Подход 1: размещение изображения над ячейкой

Плавающее изображение — это объект Picture, который находится на слое рисования рабочего листа. Хотя оно не принадлежит какой-либо одной ячейке, оно привязано к диапазону ячеек. Ячейки привязки изображения — его верхний левый и нижний правый углы — определяют его визуальную протяжённость на рабочем листе. По умолчанию только что добавленное изображение охватывает несколько ячеек. Чтобы плавающее изображение покрывало ровно одну ячейку, необходимо:

1. Добавить изображение с помощью Worksheet.getPictures().add(int row, int column, InputStream stream), что привязывает новое изображение к указанной ячейке.
2. Установить четыре свойства привязки так, чтобы ограничивающий прямоугольник изображения совпадал с целевой ячейкой.
3. Установить Picture.setPlacement в PlacementType.MOVE_AND_SIZE, чтобы изображение перемещалось и изменяло размер вместе с базовой ячейкой, когда пользователь изменяет ширину столбца или высоту строки.

Привязка изображения к одной ячейке

Привязка изображения определяется четырьмя свойствами индексов, начинающихся с нуля:

• setUpperLeftRow — индекс строки верхнего края изображения.
• setUpperLeftColumn — индекс столбца левого края изображения.
• setLowerRightRow — индекс строки нижнего края изображения. Чтобы нижний край изображения оказался у нижней границы строки r, установите это значение в r + 1.
• setLowerRightColumn — индекс столбца правого края изображения. Чтобы правый край изображения оказался у правой границы столбца c, установите это значение в c + 1.

Индексы строк и столбцов в Aspose.Cells начинаются с нуля. Ячейка C6 имеет индекс строки 5 и индекс столбца 2. Ошибки смещения на единицу в нижней правой привязке — самая распространённая причина того, что изображения, как кажется, перекрывают соседнюю ячейку.

Управление поведением размещения

getPlacement — это перечисление типа PlacementType, которое управляет поведением изображения при изменении пользователем размера находящейся под ним строки или столбца. Рекомендуемое значение для изображения в одной ячейке — PlacementType.MOVE_AND_SIZE, благодаря которому изображение перемещается и изменяет размер вместе с базовой ячейкой, сохраняя точное соответствие.

Пошаговые инструкции

1. Создайте новый Workbook (или откройте существующий).
2. Получите целевой Worksheet через workbook.getWorksheets().get(0).
3. Откройте файл изображения с диска в InputStream (как правило, FileInputStream), чтобы поток был корректно закрыт.
4. Вызовите worksheet.getPictures().add(5, 2, stream), чтобы добавить изображение, привязанное к ячейке C6. Сохраните возвращённую ссылку на Picture.
5. Установите четыре координаты привязки так, чтобы изображение покрывало только ячейку C6: setUpperLeftRow(5), setUpperLeftColumn(2), setLowerRightRow(6), setLowerRightColumn(3).
6. Установите picture.setPlacement(PlacementType.MOVE_AND_SIZE), чтобы изображение оставалось выровненным с C6 при изменении размера столбца или строки.
7. При желании добавьте образец текста в окружающие ячейки, чтобы продемонстрировать, что только ячейка C6 содержит изображение.
8. Сохраните рабочую книгу на диск как файл .xlsx. Следующий код демонстрирует полный подход.

import jpype
import asposecells
jpype.startJVM()
from asposecells.api import Workbook
from asposecells.api import Workbook, SaveFormat, PlacementType
workbook = Workbook()
worksheet = workbook.getWorksheets().get(0)
FileInputStream = jpype.JClass("java.io.FileInputStream")
fs = FileInputStream("logo.png")
try:
    picIndex = worksheet.getPictures().add(5, 2, fs)
    picture = worksheet.getPictures().get(picIndex)
    picture.setUpperLeftRow(5)
    picture.setUpperLeftColumn(2)
    picture.setLowerRightRow(6)
    picture.setLowerRightColumn(3)
    picture.setPlacement(PlacementType.MoveAndSize)
finally:
    fs.close()
workbook.save("output.xlsx", SaveFormat.Xlsx)
jpype.shutdownJVM()

Подход 2: внедрение изображения непосредственно в ячейку

Aspose.Cells также предоставляет более простой механизм для изображений, привязанных к ячейкам, — свойство Cell.setEmbeddedImage. Присвоение байтов изображения этому свойству прикрепляет изображение к самой ячейке, как если бы оно было встроенным содержимым.

Как работают внедрённые изображения

• Изображение хранится как часть содержимого ячейки, а не как фигура на слое рисования.
• Изображение автоматически масштабируется, чтобы поместиться в отображаемых границах ячейки. Никаких координат привязки или настроек размещения не требуется.
• Ячейка остаётся настоящей ячейкой с настоящим адресом, на которую можно ссылаться в формулах, сортировать как часть строки или использовать в других операциях на уровне ячеек. Это делает Cell.setEmbeddedImage наиболее лаконичным вариантом, когда ваша цель проста — «изображение, которое живёт внутри этой ячейки».

Пошаговые инструкции

1. Создайте новый Workbook (или откройте существующий).
2. Получите целевой Worksheet через workbook.getWorksheets().get(0).
3. Считайте файл изображения с диска в массив byte[] (например, вызовом Files.readAllBytes из java.nio.file.Files).
4. Получите ссылку на целевую ячейку — либо через worksheet.getCells().get("C6"), либо через worksheet.getCells().get(5, 2).
5. Присвойте массив байтов свойству ячейки setEmbeddedImage.
6. При желании настройте высоту строки и ширину столбца целевой строки и столбца, чтобы внедрённое изображение выглядело более заметным.
7. Сохраните рабочую книгу на диск как файл .xlsx. Следующий код демонстрирует полный подход.

Выбор подходящего подхода

Оба подхода дают изображение, помещающееся в одну ячейку, но они различаются способом хранения изображения и его поведением:

• Используйте плавающее изображение (Подход 1), когда:
  • Вам нужен более тонкий контроль над размещением, наслоением или выравниванием относительно других объектов рисования.
  • Вы хотите, чтобы изображение вело себя как фигура, которую можно выделять, переупорядочивать или группировать с другими фигурами.
  • Вам требуется обратная совместимость с кодом, который уже работает с PictureCollection.
  • Вам нужно динамически вычислять координаты привязки на основе макета рабочего листа.
• Используйте внедрённое изображение (Подход 2), когда:
  • Вам нужна максимально простая вставка изображения в ячейку.
  • Изображение должно перемещаться вместе с ячейкой, как любое другое содержимое ячейки.
  • Вам не нужно манипулировать изображением как фигурой.

import jpype
import asposecells
jpype.startJVM()
from asposecells.api import Workbook, SaveFormat
workbook = Workbook()
worksheet = workbook.getWorksheets().get(0)
# Get the target cell C6
cell = worksheet.getCells().get("C6")
# Read the image file into a byte array
imageData = open("logo.png", "rb").read()
# Embed the image directly into the cell
cell.setEmbeddedImage(imageData)
# Optionally adjust row height and column width so the embedded image is more visible
worksheet.getCells().setColumnWidth(2, 30)   # Column C (index 2)
worksheet.getCells().setRowHeight(5, 100)    # Row 6 (index 5)
# Save the resulting workbook as an .xlsx file
workbook.save("output.xlsx", SaveFormat.Xlsx)
jpype.shutdownJVM()