SmartMarker Single Cell Array Rendering | Aspose.Cells for Node.js via C++

Introduction

Smart Markers i Aspose.Cells är en kraftfull, mallbaserad funktion som låter dig dynamiskt fylla kalkylbladsdata med marköruttryck som &=DataSource.Field. Markören placeras i en designarbok, och när mallen bearbetas av WorkbookDesigner ersätts markörerna med värden från den angivna datakällan. Som standard, när en Smart Marker refererar till en arrayegenskap (till exempel &=DataSource.Numbers), expanderar motorn arrayen och placerar varje element i en separat intilliggande cell — antingen horisontellt över en rad eller vertikalt nedför en kolumn. Även om detta beteende är bekvämt i många scenarier finns det situationer där du skulle föredra att rendera hela arrayen i en enda cell, med elementen sammanfogade och separerade med en avgränsare du väljer. Attributen ArrayAsSingle och ExtraDelimiter, som används tillsammans inuti en Smart Marker-tagg, uppfyller exakt detta krav. De låter dig hålla rapportlayouter kompakta och förutsägbara samtidigt som du arbetar naturligt med arraydatakällor.

Why This Feature Is Needed

Default Array Spreading Behavior

När en Smart Marker refererar till en arrayegenskap expanderar Aspose.Cells arrayen över flera celler som standard. Till exempel kommer en markör som &=Product.Tags mot en string[] som innehåller fyra värden att placera varje värde i sin egen cell, vilket skjuter ut annat mallinnehåll och potentiellt bryter noggrant utformade rapportlayouter.

Use Case Limitations

Det finns många praktiska scenarier där standardspridningsbeteendet är oönskat:

  • Sammanfattningsrapporter som behöver en kompakt layout med en rad per post.
  • Tagg-, etikett- eller nyckelordslistor som behöver visas som kommaseparerade eller pipe-separerade värden inom en enda cell.
  • Filterchips eller statusindikatorer som grupperar flera värden på ett ställe för läsbarhet.
  • Nedströms pipelines (CSV-export, PDF-rendering, dokumentkoppling) som förväntar sig ett enda konsoliderat värde per cell snarare än ett expanderat intervall.
  • Plattformskompatibilitet, där vissa konsumenter inte tolererar arrayer som sprider sig över flera celler.

The Gap It Fills

Utan en inbyggd mekanism skulle utvecklare tvingas förbehandla data i JavaScript — sammanfoga arrayer till avgränsade strängar innan de binds till arbetsboksdesignern. Detta duplicerar logik, komplicerar datamodeller och ökar risken för fel. Attributen ArrayAsSingle och ExtraDelimiter eliminerar denna lösning genom att hantera formateringen deklarativt inuti själva Smart Markern.

Feature Benefits

Att använda attributen ArrayAsSingle och ExtraDelimiter i dina Smart Markers ger flera fördelar:

  • Encellinneslutning: Alla arrayelement renderas i exakt en cell, vilket håller layouter kompakta och förutsägbara.
  • Anpassad avgränsarkontroll: Ange valfri separatorsträng du vill — komma, semikolon, bindestreck, pipe, nyrad eller annan anpassad text.
  • Malldriven formatering: Ingen ytterligare kod krävs för att förbehandla datan; formateringsregler finns inuti Smart Marker-taggen.
  • Renare rapporter: Arraydata skjuter inte längre ut intilliggande mallinnehåll till olika rader eller kolumner.
  • Mångsidiga datatyper: Fungerar med strängar, nummer, datum och alla andra datatyper som kan sammanfogas med en avgränsare.
  • Bakåtkompatibilitet: När attributen utelämnas bevaras det ursprungliga spridningsbeteendet, så befintliga mallar fortsätter att fungera oförändrat.

How to Use This Feature

Smart Marker Syntax

Attributen ArrayAsSingle och ExtraDelimiter skickas som nyckel-värde-par inom parenteserna i en standard Smart Marker. Den allmänna syntaxen är:

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

Markören är sammansatt av följande delar:

  • &=DataSource.ArrayProperty — den standard Smart Marker som refererar till arrayegenskapen på den bundna datakällan.
  • arrayasSingle=true — instruerar motorn att rendera hela arrayen i en enda cell. Endast värdet true utlöser encellsbeteendet.
  • extraDelimiter=", " — definierar separatorn som placeras mellan arrayelement. Värdet är en strängliteral; det kan vara tomt, ett enskilt tecken eller en sträng med flera tecken.

Step-by-Step Workflow

Följande arbetsflöde beskriver hur man renderar en array i en enda cell med Smart Markers.

  1. Förbered datakällan: Skapa en klass (eller datastruktur) som exponerar en egenskap som returnerar en array. Egenskapen kan returnera string[], int[] eller annan arraytyp som stöds.
  2. Skapa en designarbok: Skapa en ny Workbook, lägg till en rubrikrad och placera en Smart Marker-cell som refererar till arrayegenskapen med attributen arrayasSingle och extraDelimiter.
  3. Instansiera WorkbookDesigner: Skapa ett WorkbookDesigner-objekt, bifoga designarboken till det och bind din datakälla med metoden setDataSource.
  4. Bearbeta markörerna: Anropa metoden workbookDesigner.process() för att expandera Smart Markers och fylla arbetsboken med riktig data.
  5. Spara resultatet: Spara den resulterande arbetsboken till disk i XLSX eller annat filformat som stöds.

Code Example 1 — Basic String Array Rendering

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");

Code Example 2 — Numeric Array with Custom Delimiter

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");

Code Example 3 — Comparing Default vs. ArrayAsSingle Behavior

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();
// Section 1: Default Smart Marker - values spread horizontally across cells
cells.get("A1").putValue("Default Spreading Behavior:");
cells.get("A2").putValue("&=Order.Items");
// Section 2: New single-cell rendering using arrayasSingle and extraDelimiter
cells.get("A4").putValue("Single Cell Rendering (arrayasSingle=true):");
cells.get("A5").putValue("&=Order.Items(arrayasSingle=true, extraDelimiter=\"; \")");
// Bind the data source and process Smart Markers
var designer = new AsposeCells.WorkbookDesigner(workbook);
designer.setDataSource("Order", order);
designer.process();
// Save the resulting workbook
workbook.save("output_comparison.xlsx");

Notes & Best Practices

Tänk på följande punkter när du arbetar med attributen ArrayAsSingle och ExtraDelimiter:

  • Värdet extraDelimiter behandlas som en strängliteral; escape:a alla specialtecken som din mallprocessor kan tolka.
  • Attributet arrayasSingle accepterar ett booleskt värde (true / false). Endast true utlöser encellsbeteendet; alla andra värden faller tillbaka till standardspridningsbeteendet.
  • Om arrayen är tom eller null lämnas cellen tom (eller innehåller en tom sträng beroende på datatypen).
  • Funktionen fungerar med objektdatakällor såväl som DataSet- och DataTable-källor där en kolumn kan delas upp i arrayer.
  • För nyradsseparerad utdata kan du använda \n eller os.EOL som avgränsarvärde.
  • Placera Smart Markern i en cell som har tillräcklig bredd för att visa den resulterande sammanfogade strängen; annars kan innehållet visuellt spilla över i intilliggande celler beroende på formatet.