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

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

Введение

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

• Подход 1 — разместить плавающее изображение поверх ячейки. Добавьте объект Picture на рабочий лист, установите его свойство Placement в значение MOVE_AND_SIZE и настройте опорные ячейки (getUpperLeftRow, getUpperLeftColumn, getLowerRightRow, getLowerRightColumn) так, чтобы изображение покрывало ровно одну ячейку.
• Подход 2 — встроить изображение непосредственно в ячейку. Присвойте байты изображения методу-сеттеру getEmbeddedImage() ячейки. Изображение автоматически масштабируется в соответствии с областью отображения ячейки и перемещается вместе с ней. В остальной части этой статьи рассматриваются оба подхода, объясняются соответствующие API и демонстрируется их использование в коде.

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

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

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

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

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

• Picture.getUpperLeftRow() — индекс строки верхней границы изображения.
• Picture.getUpperLeftColumn() — индекс столбца левой границы изображения.
• Picture.getLowerRightRow() — индекс строки нижней границы изображения. Чтобы нижняя граница изображения находилась у нижнего края строки r, установите значение r + 1.
• Picture.getLowerRightColumn() — индекс столбца правой границы изображения. Чтобы правая граница изображения находилась у правого края столбца c, установите значение c + 1.

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

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

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

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

1. Создайте новый объект Workbook (или откройте существующий).
2. Получите целевой объект Worksheet из workbook.getWorksheets().get(0).
3. Откройте файл изображения с диска в виде InputStream (например, FileInputStream), используя блок try-with-resources, чтобы поток был корректно закрыт.
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 com.aspose.cells.*;
import java.io.FileInputStream;
Workbook workbook = new Workbook();
Worksheet worksheet = workbook.getWorksheets().get(0);
try (FileInputStream fs = new FileInputStream("logo.png"))
{
    int picIndex = worksheet.getPictures().add(5, 2, fs);
    Picture picture = worksheet.getPictures().get(picIndex);
    picture.setUpperLeftRow(5);
    picture.setUpperLeftColumn(2);
    picture.setLowerRightRow(6);
    picture.setLowerRightColumn(3);
    picture.setPlacement(PlacementType.MOVE_AND_SIZE);
}
workbook.save("output.xlsx", SaveFormat.XLSX);

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

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

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

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

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

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

import com.aspose.cells.*;
import java.nio.file.Files;
import java.nio.file.Paths;
Workbook workbook = new Workbook();
Worksheet worksheet = workbook.getWorksheets().get(0);
// Get the target cell C6
Cell cell = worksheet.getCells().get("C6");
// Read the image file into a byte array
byte[] imageData = Files.readAllBytes(Paths.get("logo.png"));
// 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);

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

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

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

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

• Камера Excel в Aspose.Cells for Java
• Добавление полей-фильтров в сводную таблицу в Aspose.Cells for Java
• Применение стилей к сводным таблицам в Aspose.Cells for Java
• Изменение компоновки полей страниц в сводной таблице
• Преобразование спарклайна в изображение и HTML в Aspose.Cells for Java