Рендеринг массива в одну ячейку SmartMarker | Aspose.Cells for Python via .NET

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

Введение

Смарт-маркеры в Aspose.Cells — это мощная функция на основе шаблонов, которая позволяет динамически заполнять данные электронной таблицы с помощью выражений маркеров, таких как &=DataSource.Field. Маркер размещается в рабочей книге-шаблоне, и при обработке шаблона объектом WorkbookDesigner маркеры заменяются значениями из предоставленного источника данных.

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

Атрибуты ArrayAsSingle и ExtraDelimiter, используемые вместе внутри тега смарт-маркера, решают именно эту задачу. Они позволяют сохранять компактные и предсказуемые макеты отчётов, продолжая работать нативно с источниками данных в виде массивов.

Зачем нужна эта функция

Поведение по умолчанию — развёртывание массива

Когда смарт-маркер ссылается на свойство массива, Aspose.Cells по умолчанию разворачивает массив по нескольким ячейкам. Например, маркер вида &=Product.Tags при наличии массива string[] с четырьмя значениями поместит каждое значение в отдельную ячейку, сдвигая остальное содержимое шаблона и потенциально нарушая тщательно продуманные макеты отчётов.

Ограничения вариантов использования

Существует множество практических сценариев, в которых поведение развёртывания по умолчанию нежелательно:

Отчёты сводного стиля, которым необходим компактный макет с одной строкой на запись.
Списки тегов, меток или ключевых слов, которые должны отображаться как значения, разделённые запятыми или вертикальной чертой, в одной ячейке.
Чипы фильтров или индикаторы состояния, объединяющие несколько значений в одном месте для удобства чтения.
Конвейеры последующей обработки (экспорт в CSV, рендеринг в PDF, слияние почты), ожидающие одно объединённое значение в ячейке, а не развёрнутый диапазон.
Кросс-платформенная совместимость, когда некоторые потребители не допускают массивов, «расползающихся» по нескольким ячейкам.

Какую проблему решает эта функция

Без встроенного механизма разработчикам пришлось бы предварительно обрабатывать данные в Python — объединять массивы в строки с разделителями перед их привязкой к дизайнеру рабочей книги. Это дублирует логику, усложняет модели данных и увеличивает вероятность ошибок. Атрибуты ArrayAsSingle и ExtraDelimiter устраняют необходимость в подобных обходных решениях, выполняя форматирование декларативно внутри самого смарт-маркера.

Преимущества функции

Использование атрибутов ArrayAsSingle и ExtraDelimiter в смарт-маркерах даёт ряд преимуществ:

Размещение в одной ячейке: все элементы массива отображаются ровно в одной ячейке, что обеспечивает компактный и предсказуемый макет.
Управление пользовательским разделителем: укажите любую строку-разделитель — запятую, точку с запятой, дефис, вертикальную черту, перевод строки или любой другой произвольный текст.
Форматирование на уровне шаблона: для предварительной обработки данных не требуется дополнительного кода; правила форматирования задаются внутри тега смарт-маркера.
Более чистые отчёты: данные массива больше не сдвигают соседнее содержимое шаблона в другие строки или столбцы.
Универсальность типов данных: поддерживаются строки, числа, даты и любые другие типы данных, которые можно объединить с помощью разделителя.
Обратная совместимость: если атрибуты не указаны, сохраняется исходное поведение развёртывания, поэтому существующие шаблоны продолжают работать без изменений.

Как использовать эту функцию

Синтаксис смарт-маркера

Атрибуты ArrayAsSingle и ExtraDelimiter передаются в виде пар «ключ-значение» внутри круглых скобок стандартного смарт-маркера. Общий синтаксис выглядит так:

&=DataSource.ArrayProperty(arrayasSingle=true, extraDelimiter=", ")

Маркер состоит из следующих частей:

&=DataSource.ArrayProperty — стандартный смарт-маркер, ссылающийся на свойство массива в привязанном источнике данных.
arrayasSingle=true — указывает обработчику отобразить весь массив в одной ячейке. Только значение true активирует поведение «одна ячейка».
extraDelimiter=", " — задаёт разделитель, помещаемый между элементами массива. Значение является строковым литералом; оно может быть пустым, односимвольным или многосимвольным.

Атрибут extraDelimiter принимает любой строковый литерал, включая многосимвольные разделители, произвольный текст или escape-последовательности, такие как \n для вывода с переводом строки. Если массив пуст, результирующая ячейка остаётся пустой.

Пошаговый рабочий процесс

Следующий рабочий процесс описывает, как отобразить массив в одной ячейке с помощью смарт-маркеров.

Подготовьте источник данных: создайте класс (или структуру данных), который предоставляет свойство, возвращающее массив. Свойство может возвращать list[str], list[int] или любой другой поддерживаемый тип массива.
Создайте рабочую книгу-шаблон: создайте новую Workbook, добавьте строку заголовка и поместите ячейку смарт-маркера, ссылающуюся на свойство массива, с атрибутами arrayasSingle и extraDelimiter.
Создайте экземпляр WorkbookDesigner: создайте объект WorkbookDesigner, прикрепите к нему рабочую книгу-шаблон и привяжите источник данных с помощью метода set_data_source.
Обработайте маркеры: вызовите метод WorkbookDesigner.process(), чтобы развернуть смарт-маркеры и заполнить рабочую книгу реальными данными.
Сохраните результат: сохраните полученную рабочую книгу на диск в формате XLSX или в любом другом поддерживаемом формате файла.

Пример кода 1 — Базовый рендеринг строкового массива

class Product:
    def __init__(self):
        self.Tags = []

product = Product()
product.Tags = ["C#", "Aspose", "SmartMarker", "Excel"]

workbook = ac.Workbook()
worksheet = workbook.worksheets[0]

worksheet.cells["A1"].put_value("Tags")
worksheet.cells["A2"].put_value("&=Product.Tags(arrayasSingle=true, extraDelimiter=\", \")")

designer = ac.WorkbookDesigner()
designer.workbook = workbook
designer.set_data_source("Product", product)
designer.process()

workbook.save("output_arraySingle.xlsx")

Пример кода 2 — Числовой массив с пользовательским разделителем

class Student:
    def __init__(self):
        self.scores = []


student = Student()
student.scores = [95, 88, 76, 100, 67]

workbook = ac.Workbook()
worksheet = workbook.worksheets[0]

worksheet.cells["A1"].put_value("Scores")
worksheet.cells["A2"].put_value(" - ".join(str(s) for s in student.scores))

workbook.save("output_numericArray.xlsx")

Пример кода 3 — Сравнение поведения по умолчанию и ArrayAsSingle

class Order:
    def __init__(self, items):
        self._items = items

    @property
    def Items(self):
        return self._items

    @Items.setter
    def Items(self, value):
        self._items = value

order = Order(["Apple", "Banana", "Cherry", "Date"])

workbook = ac.Workbook()
sheet = workbook.worksheets[0]
cells = sheet.cells

# Раздел 1: Smart Marker по умолчанию - значения распределяются горизонтально по ячейкам
cells["A1"].put_value("Default Spreading Behavior:")
cells["A2"].put_value("&=Order.Items")

# Раздел 2: Новое отображение в одной ячейке с использованием arrayasSingle и extraDelimiter
cells["A4"].put_value("Single Cell Rendering (arrayasSingle=true):")
cells["A5"].put_value('&=Order.Items(arrayasSingle=true, extraDelimiter="; ")')

# Привязка источника данных и обработка Smart Markers
designer = ac.WorkbookDesigner(workbook)
designer.set_data_source("Order", order)
designer.process()

# Сохранение результирующей рабочей книги
workbook.save("output_comparison.xlsx")

Примечания и лучшие практики

При работе с атрибутами ArrayAsSingle и ExtraDelimiter учитывайте следующие моменты:

Значение extraDelimiter обрабатывается как строковый литерал; экранируйте любые специальные символы, которые могут быть интерпретированы вашим обработчиком шаблонов.
Атрибут arrayasSingle принимает логическое значение (True / False). Только значение True активирует поведение «одна ячейка»; любое другое значение приводит к поведению развёртывания по умолчанию.
Если массив пуст или равен null, ячейка остаётся пустой (или содержит пустую строку в зависимости от типа данных).
Функция работает как с объектными источниками данных, так и с источниками DataSet и DataTable, где столбец может быть разделён на массивы.
Для вывода с переводом строки в качестве значения разделителя можно использовать \n или os.linesep.
Размещайте смарт-маркер в ячейке, имеющей достаточную ширину для отображения результирующей объединённой строки; в противном случае содержимое может визуально перекрывать соседние ячейки в зависимости от формата.