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

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

Введение

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

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

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

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), когда:
  • нужна максимально простая вставка изображения в ячейку;
  • изображение должно перемещаться вместе с ячейкой как любое другое содержимое ячейки.

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

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