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

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

Введение

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

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

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

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

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

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

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

Добавить изображение с помощью Worksheet.Pictures.Add(int row, int column, Stream stream), который привязывает новое изображение к указанной ячейке.
Установить четыре свойства привязки так, чтобы ограничивающий прямоугольник изображения совпадал с целевой ячейкой.
Установить 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.

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

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

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

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

Создайте новую Workbook (или откройте существующую).
Получите доступ к целевому Worksheet через workbook.Worksheets[0].
Откройте файл изображения с диска в FileStream, используя блок using, чтобы поток был корректно освобождён.
Вызовите worksheet.Pictures.Add(5, 2, stream), чтобы добавить изображение, привязанное к ячейке C6. Сохраните возвращённую ссылку на Picture.
Установите четыре координаты привязки так, чтобы изображение покрывало только ячейку C6: UpperLeftRow = 5, UpperLeftColumn = 2, LowerRightRow = 6, LowerRightColumn = 3.
Установите picture.Placement = PlacementType.MoveAndSize, чтобы изображение оставалось выровненным с C6 при изменении размера столбца или строки.
При желании добавьте образец текста в окружающие ячейки, чтобы продемонстрировать, что только ячейка C6 содержит изображение.
Сохраните рабочую книгу на диск как файл .xlsx.

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

using System;
using System.IO;
using Aspose.Cells;
using Aspose.Cells.Drawing;

Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets[0];

using (FileStream fs = new FileStream("logo.png", FileMode.Open, FileAccess.Read))
{
    int picIndex = worksheet.Pictures.Add(5, 2, fs);
    Picture picture = worksheet.Pictures[picIndex];
    picture.UpperLeftRow = 5;
    picture.UpperLeftColumn = 2;
    picture.LowerRightRow = 6;
    picture.LowerRightColumn = 3;
    picture.Placement = PlacementType.MoveAndSize;
}

workbook.Save("output.xlsx", SaveFormat.Xlsx);

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

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

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

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

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

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

Создайте новую Workbook (или откройте существующую).
Получите доступ к целевому Worksheet через workbook.Worksheets[0].
Прочитайте файл изображения с диска в массив byte[] (например, с помощью File.ReadAllBytes).
Получите ссылку на целевую ячейку — либо через worksheet.Cells["C6"], либо через worksheet.Cells[5, 2].
Назначьте массив байтов свойству EmbeddedImage ячейки.
При желании настройте высоту строки и ширину столбца целевой строки и столбца, чтобы встроенное изображение выглядело более заметным.
Сохраните рабочую книгу на диск как файл .xlsx.

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

var workbook = new Workbook();
var worksheet = workbook.Worksheets[0];

// Получить целевую ячейку C6
var cell = worksheet.Cells["C6"];

// Прочитать файл изображения в массив байтов
byte[] imageData = File.ReadAllBytes("logo.png");

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

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

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

Выбор правильного подхода

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

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

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

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

Загрузка веб изображения из URL в рабочий лист Excel Вставка изображения на основе ссылки на ячейку