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

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

Введение

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

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

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

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

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

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

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

Добавить рисунок с помощью Worksheet.Pictures.Add(int row, int column, Vector<uint8_t> 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].
Считайте файл изображения с диска в буфер байтов Vector<uint8_t>, чтобы байты изображения были доступны API.
Вызовите worksheet.Pictures.Add(5, 2, imageData), чтобы добавить рисунок, привязанный к ячейке C6. Сохраните возвращённую ссылку на Picture.
Установите четыре координаты якоря так, чтобы рисунок покрывал только ячейку C6: UpperLeftRow = 5, UpperLeftColumn = 2, LowerRightRow = 6, LowerRightColumn = 3.
Установите picture.Placement = PlacementType.MoveAndSize, чтобы рисунок оставался выровненным по C6 при изменении ширины столбца или высоты строки.
При необходимости добавьте пример текста в окружающие ячейки, чтобы продемонстрировать, что только ячейка C6 содержит рисунок.
Сохраните рабочую книгу на диск в виде файла .xlsx.

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

#include "Aspose.Cells.h"
#include <fstream>
#include <vector>
#include <iterator>

using namespace Aspose::Cells;

int main() {
    Aspose::Cells::Startup();

    Workbook workbook;
    Worksheet worksheet = workbook.GetWorksheets().Get(0);

    std::ifstream fs("logo.png", std::ios::binary);
    std::vector<uint8_t> stdData((std::istreambuf_iterator<char>(fs)),
                                  std::istreambuf_iterator<char>());
    fs.close();

    Vector<uint8_t> imageData(reinterpret_cast<const uint8_t*>(stdData.data()),
                              static_cast<int32_t>(stdData.size()));

    int picIndex = worksheet.GetPictures().Add(5, 2, imageData);
    Picture picture = worksheet.GetPictures().Get(picIndex);
    picture.SetUpperLeftRow(5);
    picture.SetUpperLeftColumn(2);
    picture.SetLowerRightRow(6);
    picture.SetLowerRightColumn(3);
    picture.SetPlacement(PlacementType::MoveAndSize);

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

    Aspose::Cells::Cleanup();
    return 0;
}

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

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

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

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

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

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

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

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

#include "Aspose.Cells.h"
#include <vector>
#include <fstream>
#include <iterator>

using namespace Aspose::Cells;

int main() {
    Aspose::Cells::Startup();

    Workbook wb;
    Worksheet worksheet = wb.GetWorksheets().Get(0);

    Cell cell = worksheet.GetCells().Get(u"C6");

    // Считываем файл изображения в массив байтов
    std::ifstream file("logo.png", std::ios::binary);
    std::vector<uint8_t> stdImageData((std::istreambuf_iterator<char>(file)), std::istreambuf_iterator<char>());
    file.close();

    // Преобразуем std::vector в Aspose::Cells::Vector с помощью конструктора с указателем и размером
    Vector<uint8_t> imageData(stdImageData.data(), (int32_t)stdImageData.size());

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

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

    // Сохраняем полученную книгу как файл .xlsx
    wb.Save(u"output.xlsx", SaveFormat::Xlsx);

    Aspose::Cells::Cleanup();
    return 0;
}

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

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

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

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

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

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