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

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

Введение

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

Подход 1 — Размещение плавающего изображения над ячейкой. Добавьте Picture на рабочий лист, установите его placement в MOVE_AND_SIZE и настройте координаты привязки (upper_left_row, upper_left_column, lower_right_row, lower_right_column) так, чтобы изображение покрывало ровно одну ячейку.
Подход 2 — Встраивание изображения непосредственно в ячейку. Присвойте байты изображения свойству embedded_image ячейки. Изображение автоматически масштабируется, чтобы соответствовать области отображения ячейки, и перемещается вместе с ячейкой. В остальной части этой статьи рассматриваются оба подхода, объясняются соответствующие API и демонстрируется их использование в коде.

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

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

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

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

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

Picture.upper_left_row — индекс строки верхнего края изображения.
Picture.upper_left_column — индекс столбца левого края изображения.
Picture.lower_right_row — индекс строки нижнего края изображения. Чтобы нижний край изображения оказался на уровне нижней границы строки r, задайте значение r + 1.
Picture.lower_right_column — индекс столбца правого края изображения. Чтобы правый край изображения оказался на уровне правой границы столбца c, задайте значение c + 1.

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

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

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

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

Создайте новую Workbook (или откройте существующую).
Получите доступ к целевому Worksheet через workbook.worksheets[0].
Откройте файл изображения с диска в файловый поток (или объект BytesIO) с помощью блока with, чтобы поток был корректно освобождён.
Вызовите worksheet.pictures.add(5, 2, stream), чтобы добавить изображение, привязанное к ячейке C6. Получите возвращаемую ссылку на Picture.
Установите четыре координаты привязки так, чтобы изображение покрывало только ячейку C6: upper_left_row = 5, upper_left_column = 2, lower_right_row = 6, lower_right_column = 3.
Установите picture.placement = PlacementType.MOVE_AND_SIZE, чтобы изображение оставалось выровненным с C6 при изменении ширины столбца или высоты строки.
При необходимости добавьте образец текста в окружающие ячейки, чтобы продемонстрировать, что только ячейка C6 содержит изображение.
Сохраните книгу на диск в виде файла .xlsx. Следующий код демонстрирует полный подход.

import aspose.cells as ac
workbook = ac.Workbook()
worksheet = workbook.worksheets[0]
with open("logo.png", "rb") as fs:
    pic_index = worksheet.pictures.add(5, 2, fs)
    picture = worksheet.pictures[pic_index]
    picture.upper_left_row = 5
    picture.upper_left_column = 2
    picture.lower_right_row = 6
    picture.lower_right_column = 3
    picture.placement = ac.PlacementType.MOVE_AND_SIZE
workbook.save("output.xlsx", ac.SaveFormat.XLSX)

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

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

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

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

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

Создайте новую Workbook (или откройте существующую).
Получите доступ к целевому Worksheet через workbook.worksheets[0].
Прочитайте файл изображения с диска в объект bytes (например, открыв файл в двоичном режиме и вызвав .read()).
Получите ссылку на целевую ячейку — либо через worksheet.cells["C6"], либо через worksheet.cells[5, 2].
Присвойте объект bytes свойству embedded_image ячейки.
При необходимости настройте высоту строки и ширину столбца целевой строки и столбца, чтобы встроенное изображение выглядело более заметным.
Сохраните книгу на диск в виде файла .xlsx. Следующий код демонстрирует полный подход.

import aspose.cells as ac
workbook = ac.Workbook()
worksheet = workbook.worksheets[0]
# Get the target cell C6
cell = worksheet.cells["C6"]
# Read the image file into a byte array
with open("logo.png", "rb") as f:
    imageData = f.read()
# Embed the image directly into the cell
cell.embedded_image = imageData
# Optionally adjust row height and column width so the embedded image is more visible
worksheet.cells.set_column_width(2, 30)   # Column C (index 2)
worksheet.cells.set_row_height(5, 100)     # Row 6 (index 5)
# Save the resulting workbook as an .xlsx file
workbook.save("output.xlsx", ac.SaveFormat.XLSX)

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

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

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

Связанные статьи

Загрузка веб изображения из URL в рабочий лист Excel Вставка изображения на основе ссылки на ячейку