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

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

Введение

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

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

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

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

Поведение разворачивания массива по умолчанию

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

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

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

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

Какой пробел она заполняет

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

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

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

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

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

Синтаксис Smart Marker

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

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

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

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

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

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

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

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

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

import com.aspose.cells.*;

class Product {
    public String[] Tags;
}

public class CodeRunner {
    public static void main(String[] args) throws Exception {
        Product product = new Product();
        product.Tags = new String[] { "C#", "Aspose", "SmartMarker", "Excel" };

        Workbook workbook = new Workbook();
        Worksheet worksheet = workbook.getWorksheets().get(0);

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

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

        workbook.save("output_arraySingle.xlsx");
    }
}

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

import com.aspose.cells.*;

class Student
{
    public int[] Scores;
}

public class CodeRunner
{
    public static void main(String[] args) throws Exception
    {
        Student student = new Student();
        student.Scores = new int[] { 95, 88, 76, 100, 67 };

        Workbook workbook = new Workbook();
        Worksheet worksheet = workbook.getWorksheets().get(0);

        worksheet.getCells().get("A1").putValue("Scores");

        StringBuilder joined = new StringBuilder();
        for (int i = 0; i < student.Scores.length; i++)
        {
            if (i > 0) joined.append(" - ");
            joined.append(student.Scores[i]);
        }
        worksheet.getCells().get("A2").putValue(joined.toString());

        workbook.save("output_numericArray.xlsx");
    }
}

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

class Order
{
    private String[] items;

    public String[] getItems()
    {
        return items;
    }

    public void setItems(String[] items)
    {
        this.items = items;
    }
}

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

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

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

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

Генерация диаграммы путем обработки умных маркеров Получение уведомлений при объединении данных с помощью интеллектуальных маркеров Smart Markers