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

Введение

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

Aspose.Cells поддерживает этот сценарий двумя взаимодополняющими способами:

  • Подход 1 — размещение плавающего изображения над ячейкой. Добавьте Picture на рабочий лист, установите его Placement на MoveAndSize и настройте его якорные ячейки (UpperLeftRow, UpperLeftColumn, LowerRightRow, LowerRightColumn) так, чтобы изображение покрывало ровно одну ячейку.
  • Подход 2 — встраивание изображения непосредственно в ячейку. Присвойте байты изображения свойству ячейки EmbeddedImage. Изображение автоматически масштабируется, чтобы соответствовать области отображения ячейки, и перемещается вместе с ячейкой.

В остальной части этой статьи рассматриваются оба подхода, объясняются соответствующие API и показывается, как использовать их в коде.

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

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

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

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

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

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

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

Например, чтобы точно вписать изображение в ячейку C6 (индекс строки 5, индекс столбца 2), установите UpperLeftRow = 5, UpperLeftColumn = 2, LowerRightRow = 6 и LowerRightColumn = 3.

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

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

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

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

Следующий код демонстрирует полный подход.

var workbook = new AsposeCells.Workbook();
var worksheet = workbook.getWorksheets().get(0);

var picIndex = worksheet.getPictures().add(5, 2, "logo.png");
var picture = worksheet.getPictures().get(picIndex);
picture.setUpperLeftRow(5);
picture.setUpperLeftColumn(2);
picture.setLowerRightRow(6);
picture.setLowerRightColumn(3);
picture.setPlacement(AsposeCells.PlacementType.MoveAndSize);

workbook.save("output.xlsx", AsposeCells.SaveFormat.Xlsx);

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

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

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

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

Это делает Cell.EmbeddedImage наиболее лаконичным вариантом, когда ваша цель — просто «изображение, которое находится внутри этой ячейки».

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

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

Следующий код демонстрирует полный подход.

var workbook = new AsposeCells.Workbook();
var worksheet = workbook.getWorksheets().get(0);

// Получить целевую ячейку C6
var cell = worksheet.getCells().get("C6");

// Прочитать файл изображения в массив байтов
var imageData = fs.readFileSync("logo.png");

// Встроить изображение непосредственно в ячейку
cell.setEmbeddedImage(imageData);

// При необходимости настроить высоту строки и ширину столбца, чтобы встроенное изображение было лучше видно
worksheet.getCells().setColumnWidth(2, 30);   // Столбец C (индекс 2)
worksheet.getCells().setRowHeight(5, 100);     // Строка 6 (индекс 5)

// Сохранить полученную книгу как файл .xlsx
workbook.save("output.xlsx", AsposeCells.SaveFormat.Xlsx);

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

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

  • Используйте плавающее изображение (Подход 1), когда:

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

  • Используйте встроенное изображение (Подход 2), когда:

    • Вам нужна максимально простая вставка изображения в ячейку.
    • Изображение должно перемещаться вместе с ячейкой, как любое другое содержимое ячейки.
    • Вам не нужно манипулировать изображением как фигурой.
Производительность Спарклайны в Aspose.Cells для Aspose.Cells для Node.js через Java