Klarere Excel-Diagramme in JavaScript: Mehrstufige Beschriftungen & duale Achsen

Ein Säulendiagramm mit Regionen und Monaten auf derselben Achse hat zwei Probleme, und diese Probleme sind nicht dieselben. Das erste ist, dass die Kategoriebeschriftungen in einer einzigen Zeile zusammenfallen — "Nord", "Jan", "Nord", "Feb" — und der Leser mental neu gruppieren muss, welcher Monat zu welcher Region gehört. Das zweite ist, dass wenn eine Wachstumsraten-Reihe neben einer Umsatzreihe hinzugefügt wird, die in die Millionen geht, die Wachstumsrate zu einer flachen Linie wird, die an der Grundlinie klebt, weil eine einzige Wertachse nicht zwei Größenordnungen gleichzeitig bedienen kann.

Mehrstufige Kategoriebeschriftungen beheben das erste Problem. Eine Sekundärachse behebt das zweite. Es sind unabhängige Funktionen, die zufällig im selben Diagramm nützlich sind, und Spire.XLS for JavaScript behandelt beide über die Diagrammachsen-API — direkt im Browser auf WebAssembly, wobei Dateien durch ein virtuelles Dateisystem (VFS) laufen und kein Backend beteiligt ist.

Zur Projekteinrichtung siehe Spire.XLS for JavaScript in ein React-Projekt integrieren. Die folgenden Beispiele gehen davon aus, dass das Paket installiert und das WebAssembly-Modul initialisiert wurde.

Wenn eine Achse nicht ausreicht

Die beiden Probleme treten in derselben Art von Arbeitsblatt auf — eines, bei dem die Kategorien eine Hierarchie haben und die Werte eine Streuung aufweisen —, aber sie stammen von unterschiedlichen Stellen:

Keines von beiden ist ein Styling-Problem. Bei beiden geht es darum, dass die Achse etwas nicht weiß, was sie wissen müsste — dass die Kategorien Ebenen haben oder dass die Werte inkompatible Skalen haben. Die beiden folgenden Abschnitte behandeln sie der Reihe nach, und der zweite baut auf dem ersten auf, sodass das endgültige Diagramm beide Korrekturen enthält.

Voraussetzungen

Sie benötigen ein React-Projekt mit installiertem Spire.XLS for JavaScript und einem initialisierten WebAssembly-Modul, erreichbar unter window.wasmModule.spirexls. Das Beispiel lädt eine Schriftart und eine vorbereitete Datendatei in das VFS, bevor das Diagramm erstellt wird, und beide werden aus dem öffentlichen Ordner des Projekts abgerufen.

Die Daten hinter mehrstufigen Beschriftungen

Mehrstufige Beschriftungen werden nicht allein durch eine Eigenschaft erstellt — sie werden aus den Daten gelesen. Die Kategorieachse zeichnet so viele Beschriftungsebenen, wie es Spalten in dem Bereich gibt, auf den CategoryLabels zeigt. Daher muss das Arbeitsblatt mit der Hierarchie über die Spalten hinweg angelegt werden:

Die äußeren Beschriftungen in Spalte A sind über die Zeilen, die sie abdecken, verbunden — "Nord" erstreckt sich über die beiden Zeilen für Jan und Feb. Diese Zusammenführung ist es, die die Ebene beim Rendern des Diagramms visuell zu einer einzigen Beschriftung pro Gruppe zusammenfallen lässt. Ohne sie zeigt die Achse zwar weiterhin zwei Ebenen, aber die äußere Ebene wiederholt die Beschriftung in jeder Zeile, statt zu gruppieren.

Dies ist eine Frage des Datenlayouts, nicht der Diagramm-API. Der Diagrammcode muss CategoryLabels nur auf beide Spalten zeigen lassen; ob die äußeren Zellen verbunden sind, wird in der Arbeitsmappe entschieden, nicht im Diagrammobjekt.

Ein Diagramm mit mehrstufigen Kategoriebeschriftungen erstellen

Sobald die Daten angelegt sind, tut der Diagrammcode zwei Dinge: Er zeigt CategoryLabels auf einen Bereich, der sowohl die äußere als auch die innere Spalte umfasst, und er aktiviert MultiLevelLable, damit die Achse diese Spalten zu gestapelten Zeilen erweitert. Die Schritte sind:

1. Laden Sie die Schriftart und die Testdatendatei in das VFS.
2. Laden Sie die Arbeitsmappe und holen Sie das Arbeitsblatt.
3. Fügen Sie ein Säulendiagramm hinzu und fügen Sie eine benannte Umsatzreihe hinzu.
4. Richten Sie die Kategoriebeschriftungen sowohl auf die Regions- als auch auf die Monatsspalte.
5. Aktivieren Sie mehrstufige Beschriftungen für die Kategorieachse und speichern Sie die Arbeitsmappe.

function App() {
  const createMultiLevelChart = async () => {
    // Get the Spire.XLS WASM module
    const xlsModule = window.wasmModule?.spirexls;

    // Check if the module is ready
    if (!xlsModule) {
      alert('Spire.Xls is not ready yet');
      return;
    }

    // Load the font and the test data file into the VFS
    await window.spire.FetchFileToVFS('ARIAL.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
    const inputFileName = 'MultiLevelChartData.xlsx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}data/`);

    // Load the workbook and get the first worksheet
    const workbook = new xlsModule.Workbook();
    workbook.LoadFromFile({ fileName: inputFileName });
    const sheet = workbook.Worksheets.get(0);

    // Add a column chart
    const chart = sheet.Charts.Add({ chartType: xlsModule.ExcelChartType.ColumnClustered });
    chart.ChartTitle = "Sales";
    chart.Legend.Delete();

    // Add the sales series and give it a name
    const serie = chart.Series.Add({ name: "Sales", serieType: xlsModule.ExcelChartType.ColumnClustered });
    serie.Values = sheet.Range.get("C2:C7");

    // Point the category labels at both the region and the month column
    serie.CategoryLabels = sheet.Range.get("A2:B7");

    // Turn on multi-level category labels so each level gets its own row
    chart.PrimaryCategoryAxis.MultiLevelLable = true;

    // Place the chart on the worksheet
    chart.LeftColumn = 5;
    chart.TopRow = 1;
    chart.RightColumn = 14;

    // Save the workbook
    const outputFileName = "MultiLevelLabels.xlsx";
    workbook.SaveToFile({ fileName: outputFileName });

    // Dispose of the workbook object to free resources
    workbook.Dispose();

    // Read the result file from the VFS and trigger the download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Multi-Level Labels</h1>
      <button onClick={createMultiLevelChart}>Start</button>
    </div>
  );
}

export default App;

Ein Diagramm mit mehrstufigen Kategoriebeschriftungen, jede Ebene in einer eigenen Zeile

Der Bereich A2:B7 ist es, der die Achse zwei Ebenen anzeigen lässt. Das Binden eines einspaltigen Bereichs wie B2:B7 würde auch bei auf true gesetztem MultiLevelLable nur eine Ebene erzeugen — die Eigenschaft steuert, ob mehrere Ebenen in Zeilen erweitert werden, nicht, ob überhaupt eine Datenebene zum Erweitern vorhanden ist.

Warum die Wachstumsreihe verschwindet

Fügen Sie eine zweite Reihe für das Jahr-über-Jahr-Wachstum hinzu — Werte im niedrigen zweistelligen Prozentbereich — und tragen Sie sie auf derselben Wertachse wie den Umsatz auf. Die Umsatzsäulen erreichen 120.000; die Wachstumsrate erreicht 12. Auf einer Achse, die von 0 bis 140.000 skaliert, ist die Zahl 12 nicht von null zu unterscheiden. Die Reihe ist vorhanden, die Daten sind korrekt, und das Diagramm zeigt eine flache Linie an der Grundlinie.

Dies ist kein Fehler in den Daten oder im Diagramm. Es ist die Wertachse, die ihre Aufgabe erfüllt — einen Bereich abbildet, der die größte Reihe abdeckt — auf Kosten der kleinsten. Die einzige Möglichkeit, beide Reihen klar zu sehen, besteht darin, jeder ihre eigene Skala zu geben, und genau das tut die Sekundärachse.

Eine Reihe auf die Sekundärachse verschieben

Die Wachstumsreihe wird als Linie statt als Säule hinzugefügt. Eine Linie beansprucht keine Balkenbreite und lässt sich daher klar neben der Säulenreihe lesen, die dieselben Kategorien teilt. Sie von der primären Achse zu entfernen ist eine einzige Eigenschaft: UsePrimaryAxis = false. Die Schritte sind:

1. Laden Sie die Schriftart und die Testdatendatei in das VFS.
2. Laden Sie die Arbeitsmappe und holen Sie das Arbeitsblatt.
3. Fügen Sie ein Säulendiagramm hinzu und fügen Sie eine benannte Umsatzreihe hinzu.
4. Fügen Sie die Wachstumsreihe als Linie hinzu.
5. Verschieben Sie die Wachstumsreihe auf die Sekundärachse und speichern Sie die Arbeitsmappe.

function App() {
  const addSecondaryAxis = async () => {
    // Get the Spire.XLS WASM module
    const xlsModule = window.wasmModule?.spirexls;

    // Check if the module is ready
    if (!xlsModule) {
      alert('Spire.Xls is not ready yet');
      return;
    }

    // Load the font and the test data file into the VFS
    await window.spire.FetchFileToVFS('ARIAL.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
    const inputFileName = 'MultiLevelChartData.xlsx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}data/`);

    // Load the workbook and get the first worksheet
    const workbook = new xlsModule.Workbook();
    workbook.LoadFromFile({ fileName: inputFileName });
    const sheet = workbook.Worksheets.get(0);

    // Add a column chart
    const chart = sheet.Charts.Add({ chartType: xlsModule.ExcelChartType.ColumnClustered });
    chart.ChartTitle = "Sales and YoY Growth";

    // Add the sales series, which stays on the primary axis
    const salesSerie = chart.Series.Add({ name: "Sales", serieType: xlsModule.ExcelChartType.ColumnClustered });
    salesSerie.Values = sheet.Range.get("C2:C7");

    // Point the category labels at both the region and the month column
    salesSerie.CategoryLabels = sheet.Range.get("A2:B7");

    // Add the growth series as a line
    const growthSerie = chart.Series.Add({ name: "YoY Growth", serieType: xlsModule.ExcelChartType.Line });
    growthSerie.Values = sheet.Range.get("D2:D7");

    // Move the growth series to the secondary axis so it plots on its own percentage scale
    growthSerie.UsePrimaryAxis = false;

    // Turn on multi-level category labels
    chart.PrimaryCategoryAxis.MultiLevelLable = true;

    // Place the chart on the worksheet
    chart.LeftColumn = 5;
    chart.TopRow = 1;
    chart.RightColumn = 14;

    // Save the workbook
    const outputFileName = "SecondaryAxis.xlsx";
    workbook.SaveToFile({ fileName: outputFileName });

    // Dispose of the workbook object to free resources
    workbook.Dispose();

    // Read the result file from the VFS and trigger the download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Secondary Axis</h1>
      <button onClick={addSecondaryAxis}>Start</button>
    </div>
  );
}

export default App;

Ein Säulendiagramm mit einer Sekundärachse für die Linienreihe der Wachstumsrate

UsePrimaryAxis = false wirkt sich nur auf die Reihe aus, bei der es gesetzt ist; jede andere Reihe bleibt auf der primären Achse. Das Diagramm erhält ein zweites Paar aus Wert- und Kategorieachse, wodurch es zwei separate Skalenbereiche hat. Series.Add nimmt den Reihennamen gleichzeitig entgegen, sodass die Legende den übergebenen Namen anzeigt und nicht ein automatisch generiertes "Series 1".

Die Skalierung der Sekundärachse festlegen

Sobald eine Reihe auf die Sekundärachse verschoben wurde, berechnet diese Achse ihre eigene Skalierung — und zwar unabhängig von der primären. Die beiden Bereiche wissen nichts voneinander, was bedeutet, dass die Sekundärachse Grenzen wählen kann, die nicht gut zu den Daten passen.

PrimaryValueAxis.MinValue, MaxValue und MajorUnit steuern nur die primäre Achse. Um die Skalierung der Sekundärachse festzulegen, verwenden Sie SecondaryValueAxis:

// Give the secondary axis a 0-20 scale with a major unit of 5
chart.SecondaryValueAxis.MinValue = 0;
chart.SecondaryValueAxis.MaxValue = 20;
chart.SecondaryValueAxis.MajorUnit = 5;

Legen Sie die Skalierung nach dem Verschieben der Reihe auf die Sekundärachse fest. Solange keine Reihe die Sekundärachse verwendet, wird die Zuweisung akzeptiert, aber nie in die Datei geschrieben — die Achse existiert in der Ausgabe erst, wenn eine Reihe darauf dargestellt wird.

Häufige Probleme

Die Kategorieachse zeigt nur eine Ebene von Beschriftungen. CategoryLabels zeigt auf einen einspaltigen Bereich. Die Anzahl der Ebenen wird dadurch bestimmt, wie viele Spalten der Bereich umfasst, nicht durch die Eigenschaft MultiLevelLable. Richten Sie es auf einen mehrspaltigen Bereich wie A2:B7, und stellen Sie sicher, dass die äußeren Beschriftungszellen in den Daten verbunden sind.

Die Skalierung der Sekundärachse sieht falsch aus. Die primäre und die sekundäre Wertachse berechnen ihre Skalierungen unabhängig voneinander. Das Setzen von MinValue oder MaxValue auf PrimaryValueAxis wirkt sich nicht auf die Sekundärachse aus. Verwenden Sie chart.SecondaryValueAxis, um ihre Skalierung direkt festzulegen, und tun Sie dies, nachdem Sie eine Reihe darauf verschoben haben.

Die Wachstumsreihe erscheint auch nach dem Hinzufügen einer Sekundärachse noch flach. Prüfen Sie, ob UsePrimaryAxis = false bei der Wachstumsreihe gesetzt ist und nicht bei der Umsatzreihe. Die Eigenschaft gilt pro Reihe — wenn Sie sie bei der falschen Reihe setzen, wird die falsche auf die Sekundärachse verschoben.

Die Legende zeigt "Series 1" statt des Reihennamens. Der Name wurde nicht an Series.Add übergeben. Verwenden Sie chart.Series.Add({ name: "Sales", ... }), damit die Legende den von Ihnen beabsichtigten Namen übernimmt und nicht eine automatisch generierte Beschriftung.

FAQ

Kann ich mehr als zwei Ebenen von Kategoriebeschriftungen haben?

Ja. Die Anzahl der Ebenen wird durch die Anzahl der Spalten bestimmt, die der Bereich CategoryLabels umfasst. Ein dreispaltiger Bereich erzeugt drei Ebenen — zum Beispiel Jahr, Quartal und Monat. Die äußeren Beschriftungszellen müssen in den Daten verbunden sein, damit jede Ebene korrekt gruppiert wird.

Funktioniert die Sekundärachse auch mit anderen Diagrammtypen als Säule und Linie?

Ja. Die Sekundärachse ist nicht an einen bestimmten Diagrammtyp gebunden. Das übliche Muster ist Säule plus Linie — die Linie beansprucht keine Balkenbreite und lässt sich klar neben den Säulen lesen —, aber jede Reihe kann durch Setzen von UsePrimaryAxis = false auf die Sekundärachse verschoben werden.

Muss Excel installiert sein, um diese Diagramme zu erstellen?

Nein. Die Tabellenkalkulations-Engine ist im Paket enthalten und läuft als WebAssembly im Browser. Die Arbeitsmappe wird vollständig clientseitig erstellt, mit Diagrammen versehen und gespeichert.

Kann ich die sekundäre Kategorieachse separat steuern?

Wenn eine Reihe auf die Sekundärachse verschoben wird, erhält das Diagramm zusätzlich zur sekundären Wertachse eine sekundäre Kategorieachse. Die beiden Kategorieachsen teilen sich standardmäßig dieselben Kategoriebeschriftungen, sodass mehrstufige Beschriftungen für beide gelten.

Ist die Ausgabedatei mit Excel kompatibel?

Ja. Die Arbeitsmappe wird als .xlsx gespeichert, und das Diagramm — einschließlich mehrstufiger Beschriftungen und Sekundärachse — wird als standardmäßiges Diagramm-XML geschrieben, das Excel nativ liest.

Siehe auch

• Spire.XLS for JavaScript in ein React-Projekt integrieren
• Spire.XLS for JavaScript Produktseite