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

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.

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

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

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

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

Создайте новый Workbook (или откройте существующий).
Получите целевой Worksheet из workbook.GetWorksheets().Get(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.GetWorksheets().Get(0].
Прочитайте файл изображения с диска в массив байтов Vector<uint8_t>.
Получите ссылку на целевую ячейку — либо через worksheet.GetCells().Get("C6")], либо worksheet.GetCells().Get(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++