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

Введение

Смарт-маркеры в 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=", " — определяет разделитель, помещаемый между элементами массива. Значение представляет собой строковый литерал; оно может быть пустым, одним символом или строкой из нескольких символов.

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

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

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

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

const AsposeCells = require("aspose.cells.node");
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 — Числовой массив с пользовательским разделителем

const AsposeCells = require("aspose.cells.node");
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

const AsposeCells = require("aspose.cells.node");
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.
  • Поместите смарт-маркер в ячейку, которая имеет достаточную ширину для отображения результирующей объединённой строки; в противном случае содержимое может визуально переполниться в соседние ячейки в зависимости от формата.