Рендеринг массива смарт-маркера в одной ячейке | Aspose.Cells Python via Java

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 для вывода с переводом строки. Если массив пуст, результирующая ячейка остаётся пустой.

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

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

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

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

import jpype
import asposecells
jpype.startJVM()
from asposecells.api import Workbook
from asposecells.api import Workbook, WorkbookDesigner

class Product:
    def __init__(self, tags):
        self._tags = tags
    
    def getTags(self):
        return self._tags

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

workbook = Workbook()
worksheet = workbook.getWorksheets().get(0)

worksheet.getCells().get("A1").putValue("Tags")
worksheet.getCells().get("A2").putValue("&=Product.Tags(arrayasSingle=true, extraDelimiter=\", \")")

designer = WorkbookDesigner()
designer.setWorkbook(workbook)
designer.setDataSource("Product", product)
designer.process()

workbook.save("output_arraySingle.xlsx")

jpype.shutdownJVM()

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

import jpype
import asposecells
jpype.startJVM()
from asposecells.api import Workbook
from asposecells.api import Workbook

# Определение класса Student
class Student:
    def __init__(self):
        self.Scores = []

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

workbook = Workbook()
worksheet = workbook.getWorksheets().get(0)

worksheet.getCells().get("A1").putValue("Scores")
worksheet.getCells().get("A2").putValue(" - ".join(str(s) for s in student.Scores))

workbook.save("output_numericArray.xlsx")

jpype.shutdownJVM()

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

import jpype
import asposecells
jpype.startJVM()
from asposecells.api import Workbook
from asposecells.api import Workbook, WorkbookDesigner

# Определяем источник данных как словарь (эквивалент класса Order)
order = {"Items": ["Apple", "Banana", "Cherry", "Date"]}

workbook = Workbook()
sheet = workbook.getWorksheets().get(0)
cells = sheet.getCells()

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

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

# Привязываем источник данных и обрабатываем смарт-маркеры
designer = WorkbookDesigner(workbook)
designer.setDataSource("Order", order)
designer.process()

# Сохраняем полученную рабочую книгу
workbook.save("output_comparison.xlsx")

jpype.shutdownJVM()

Примечания и рекомендации

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

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

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

• Смарт-маркеры