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

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

Введение

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

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

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

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. Следующий код демонстрирует полный подход.

const AsposeCells = require("aspose.cells-node");
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. Следующий код демонстрирует полный подход.

const AsposeCells = require("aspose.cells-node");
const fs = require("fs");
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), когда:
  • Вам нужна максимально простая вставка изображения в ячейку.
  • Изображение должно перемещаться вместе с ячейкой, как и любое другое содержимое ячейки.