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

Введение

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

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

  • Подход 1 — Размещение плавающего изображения над ячейкой. Добавьте объект Picture на рабочий лист, установите его свойство placement в значение MoveAndSize и настройте его опорные ячейки (upperLeftRow, upperLeftColumn, lowerRightRow, lowerRightColumn) так, чтобы изображение покрывало ровно одну ячейку.
  • Подход 2 — Встраивание изображения непосредственно в ячейку. Присвойте байты изображения свойству ячейки embeddedImage. Изображение автоматически масштабируется под область отображения ячейки и перемещается вместе с ней.

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

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

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

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

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

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

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

  • picture.upperLeftRow — индекс строки верхнего края изображения.
  • picture.upperLeftColumn — индекс столбца левого края изображения.
  • picture.lowerRightRow — индекс строки нижнего края изображения. Чтобы нижний край изображения находился у нижней границы строки r, задайте значение r + 1.
  • picture.lowerRightColumn — индекс столбца правого края изображения. Чтобы правый край изображения находился у правой границы столбца c, задайте значение c + 1.

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

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

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

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

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

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

const AsposeCells = require("aspose.cells");
const fs = require("fs");

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

const fs_stream = fs.createReadStream("logo.png");
const picIndex = worksheet.getPictures().add(5, 2, fs_stream);
const 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.worksheets[0].
  3. Прочитайте файл изображения с диска в Buffer или массив байтов с помощью API файловой системы Node.js (например, fs.readFileSync).
  4. Получите ссылку на целевую ячейку — либо через worksheet.cells["C6"], либо через worksheet.cells[5, 2].
  5. Присвойте массив байтов свойству ячейки embeddedImage.
  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), когда:

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

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

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

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

Загрузка веб изображения по URL в лист Excel с помощью Node.js via C++ Вставка изображения на основе ссылки на ячейку с помощью Node.js via C++