Рендеринг массива в одной ячейке SmartMarker | Aspose.Cells for Node.js via C++

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

Введение

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

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

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

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

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

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

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

Какую проблему она решает

Без встроенного механизма разработчикам пришлось бы предварительно обрабатывать данные в JavaScript — объединять массивы в строки с разделителями перед привязкой их к дизайнеру рабочей книги. Это дублирует логику, усложняет модели данных и увеличивает вероятность ошибок. Атрибуты 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, прикрепите к нему рабочую книгу дизайнера и привяжите ваш источник данных с помощью метода setDataSource.
4. Обработайте маркеры: вызовите метод workbookDesigner.process(), чтобы развернуть смарт-маркеры и заполнить рабочую книгу реальными данными.
5. Сохраните результат: сохраните полученную рабочую книгу на диск в формате XLSX или любом другом поддерживаемом формате файла.

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

let product = {
    Tags: ["C#", "Aspose", "SmartMarker", "Excel"]
};
let workbook = new AsposeCells.Workbook();
let worksheet = workbook.getWorksheets().get(0);
worksheet.getCells().get("A1").putValue("Tags");
worksheet.getCells().get("A2").putValue('&=Product.Tags(arrayasSingle=true, extraDelimiter=", ")');
let designer = new AsposeCells.WorkbookDesigner();
designer.setWorkbook(workbook);
designer.setDataSource("Product", product);
designer.process();
workbook.save("output_arraySingle.xlsx");

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

class Student {
    constructor() {
        this.Scores = [];
    }
}
const student = new Student();
student.Scores = [95, 88, 76, 100, 67];
const workbook = new AsposeCells.Workbook();
const worksheet = workbook.getWorksheets().get(0);
worksheet.getCells().get("A1").putValue("Scores");
worksheet.getCells().get("A2").putValue(student.Scores.join(" - "));
workbook.save("output_numericArray.xlsx");

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

var order = {
    Items: ["Apple", "Banana", "Cherry", "Date"]
};
var workbook = new AsposeCells.Workbook();
var sheet = workbook.getWorksheets().get(0);
var 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=\"; \")");
// Привязка источника данных и обработка смарт-маркеров
var designer = new AsposeCells.WorkbookDesigner(workbook);
designer.setDataSource("Order", order);
designer.process();
// Сохранение результирующей книги
workbook.save("output_comparison.xlsx");

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

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

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