Рендеринг массива 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.

1. Подготовьте источник данных: создайте класс (или структуру данных), который предоставляет свойство, возвращающее массив. Свойство может возвращать String[], int[] или любой другой поддерживаемый тип массива.
2. Создайте рабочую книгу дизайнера: создайте новый Workbook, добавьте строку заголовка и поместите ячейку Smart Marker, которая ссылается на свойство массива с атрибутами arrayasSingle и extraDelimiter.
3. Создайте экземпляр WorkbookDesigner: создайте объект WorkbookDesigner, прикрепите к нему рабочую книгу дизайнера и привяжите ваш источник данных с помощью метода setDataSource.
4. Обработайте маркеры: вызовите метод WorkbookDesigner.process() для разворачивания Smart Markers и заполнения рабочей книги реальными данными.
5. Сохраните результат: сохраните полученную рабочую книгу на диск в формате 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 в ячейку, которая имеет достаточную ширину для отображения результирующей объединённой строки; в противном случае содержимое может визуально переполняться в соседние ячейки в зависимости от формата.