Linienformen in Excel mit JavaScript (React) einfügen

Ein Arbeitsblatt ist nicht immer nur ein Raster aus Zahlen. Manchmal ist es eine Leinwand – ein zwischen Datenblöcken skizziertes Flussdiagramm, ein Beziehungsdiagramm, das Teams mit Projekten verbindet, ein Callout, der von einer Notiz auf die Zelle zeigt, die er kommentiert. In all diesen Fällen ist das fehlende Element eine Linie: ein gerader Strich zwischen zwei Kästen, ein geschwungener Bogen um einen Bereich, ein Ellbogen-Verbinder, der einmal abknickt und weiterläuft.

Spire.XLS for JavaScript bietet einer React-App die Methode sheet.Lines.AddLine() zum Einfügen von Linienformen an einer bestimmten Position, mit vier Linientypen, die über die Enumeration LineShapeType verfügbar sind, und voller Kontrolle über Strichstil, Farbe und Stärke. Alles läuft im Browser auf WebAssembly – kein Backend, keine Excel-Automatisierung, kein Datei-Upload.

Zur Projekteinrichtung siehe Integrating Spire.XLS for JavaScript in a React Project. Die folgenden Beispiele setzen voraus, dass das Paket installiert und das WebAssembly-Modul initialisiert wurde.

Wann ein Arbeitsblatt Linien benötigt

Linien in einem Arbeitsblatt dienen drei übergeordneten Zwecken, und der Linientyp, zu dem Sie greifen, hängt davon ab, welcher davon gerade vor Ihnen liegt:

Der Fall mit der Pfeilspitze – bei dem die Linie eine Richtung anzeigen muss – verwendet eine andere API, TypedLines.AddLine(), die Pfeilstile an beiden Enden und pixelgenaue Positionierung unterstützt. Dies wird separat behandelt in Add Arrow Connectors in Excel in JavaScript (React). Dieser Artikel konzentriert sich auf Lines.AddLine(), das die vier grundlegenden Linienformen und ihre visuelle Gestaltung abdeckt.

Voraussetzungen

Sie benötigen ein React-Projekt mit installiertem Spire.XLS for JavaScript und initialisiertem WebAssembly-Modul, erreichbar unter window.wasmModule.spirexls. Das Beispiel lädt eine Schriftart in das VFS zur Textmessung und speichert mit dem Excel-2010-Versionsflag.

Die vier Linientypen

LineShapeType stellt vier Formen bereit, und der Unterschied zwischen ihnen ist geometrisch – wie die Linie von ihrem Anfang zu ihrem Ende verläuft:

Alle vier werden durch dieselbe Methode erstellt – sheet.Lines.AddLine() –, wobei der Parameter lineShapeType auswählt, welche gezeichnet wird. Die Erscheinungseigenschaften (DashStyle, Color, Weight) gelten für alle vier gleichermaßen.

Linien in ein Arbeitsblatt einfügen

Das Beispiel fügt je einen Vertreter jedes Linientyps in ein neues Arbeitsblatt ein, jeder mit einem eigenen Strichstil und einer eigenen Farbe, damit die vier Formen in der Ausgabe unterscheidbar sind. Die Schritte sind:

1. Ein Workbook-Objekt erstellen und das erste Arbeitsblatt abrufen.
2. Worksheet.Lines.AddLine() viermal aufrufen und dabei jeweils Positionsparameter und einen anderen LineShapeType übergeben.
3. DashStyle, Color und Weight jeder Linie anpassen.
4. Die Arbeitsmappe mit Workbook.SaveToFile() speichern.

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

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

    // Load the font into the VFS for text measurement and column auto-fit
    await window.spire.FetchFileToVFS('ARIAL.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);

    // Create a new workbook and get the first worksheet
    const workbook = new xlsModule.Workbook();
    const sheet = workbook.Worksheets.get(0);

    // Add a straight line - solid, CadetBlue, weight 2, with arrow
    let line1 = sheet.Lines.AddLine({ row: 10, column: 2, width: 200, height: 1, lineShapeType: xlsModule.LineShapeType.Line });
    line1.DashStyle = xlsModule.ShapeDashLineStyleType.Solid;
    line1.Color = xlsModule.Color.get_CadetBlue();
    line1.Weight = 2;
    line1.EndArrowHeadStyle = xlsModule.ShapeArrowStyleType.LineArrow;

    // Add a curved line - dotted, OrangeRed, weight 2
    let line2 = sheet.Lines.AddLine({ row: 12, column: 2, width: 200, height: 1, lineShapeType: xlsModule.LineShapeType.CurveLine });
    line2.DashStyle = xlsModule.ShapeDashLineStyleType.Dotted;
    line2.Color = xlsModule.Color.get_OrangeRed();
    line2.Weight = 2;

    // Add an elbow connector - DashDotDot, Purple, weight 2
    let line3 = sheet.Lines.AddLine({ row: 14, column: 2, width: 200, height: 1, lineShapeType: xlsModule.LineShapeType.ElbowLine });
    line3.DashStyle = xlsModule.ShapeDashLineStyleType.DashDotDot;
    line3.Color = xlsModule.Color.get_Purple();
    line3.Weight = 2;

    // Add an inverted line - Dashed, Green, weight 2
    let line4 = sheet.Lines.AddLine({ row: 16, column: 2, width: 200, height: 1, lineShapeType: xlsModule.LineShapeType.LineInv });
    line4.DashStyle = xlsModule.ShapeDashLineStyleType.Dashed;
    line4.Color = xlsModule.Color.get_Green();
    line4.Weight = 2;

    // Save the workbook
    const outputFileName = 'AddLineShapes.xlsx';
    workbook.SaveToFile({ fileName: outputFileName, version: xlsModule.ExcelVersion.Version2010 });

    // Release resources
    workbook.Dispose();

    // Read the saved 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>Add Line Shapes</h1>
      <button onClick={addLineShapes}>Start</button>
    </div>
  );
}

export default App;

Vier Linientypen, die in ein Arbeitsblatt eingefügt wurden: gerade, geschwungen, Ellbogen und umgekehrt

Die erste Linie legt außerdem EndArrowHeadStyle fest, wodurch sie am Ende eine Pfeilspitze erhält – Lines.AddLine() unterstützt einen einzelnen Pfeilstil am Ende, aber nicht am Anfang. Für Pfeile an beiden Enden oder pixelgenaue Positionierung verwenden Sie stattdessen TypedLines.AddLine(), behandelt in Add Arrow Connectors in Excel in JavaScript (React).

Das Erscheinungsbild von Linien anpassen

Drei Eigenschaften steuern, wie eine Linie aussieht, und sie sind unabhängig voneinander – das Ändern einer setzt die anderen nicht zurück:

Der Strichstil ist derjenige, mit dem es sich zu experimentieren lohnt. Eine durchgezogene Linie wirkt wie eine dauerhafte Verbindung; eine gepunktete Linie wirkt wie eine vorläufige oder optionale; eine gestrichelte Linie wirkt wie eine Grenze. In einem Flussdiagramm, in dem einige Verbindungen bedingt sind, vermittelt die Verwendung von Solid für den Hauptfluss und Dashed für die bedingten Verzweigungen den Unterschied ohne Legende.

Positionierung nach Zeile und Spalte

Lines.AddLine() platziert eine Linie anhand von Zeilen- und Spaltenkoordinaten sowie einer Breite und Höhe:

sheet.Lines.AddLine({ row: 10, column: 2, width: 200, height: 1, lineShapeType: xlsModule.LineShapeType.Line });

• row und column legen den Ankerpunkt fest – wo die Linie beginnt.
• width legt die horizontale Ausdehnung in Pixeln fest.
• height legt die vertikale Ausdehnung in Pixeln fest. Eine Höhe von 1 erzeugt eine horizontale Linie; eine Breite von 1 erzeugt eine vertikale.

Dies ist ein hybrides System: Der Anker wird in Tabellenkalkulationseinheiten (Zeilen und Spalten) angegeben, die Größe jedoch in Pixeln. Das macht es einfach, eine Linie an einer bestimmten Zelle auszurichten – übergeben Sie einfach deren Zeile und Spalte –, aber die Länge muss Spaltenbreiten und Zeilenhöhen berücksichtigen, die variieren. Wenn Sie volle pixelgenaue Kontrolle sowohl über die Startposition als auch über die Größe benötigen, bietet TypedLines.AddLine() Top und Left in Pixeln.

Häufige Probleme

Die Linie ist in der Ausgabe nicht sichtbar. Prüfen Sie Weight und Color. Eine Stärke von 0 oder eine Farbe, die dem Hintergrund entspricht, erzeugt eine unsichtbare Linie. Vergewissern Sie sich außerdem, dass row und column die Linie innerhalb des verwendeten Bereichs des Arbeitsblatts platzieren – eine in Zeile 1000 auf einem leeren Blatt verankerte Linie wird gezeichnet, liegt aber außerhalb des sichtbaren Bereichs.

Die Pfeilspitze fehlt. EndArrowHeadStyle wurde nicht festgelegt oder auf LineNoArrow gesetzt. Weisen Sie ShapeArrowStyleType.LineArrow zu, um am Ende der Linie eine Pfeilspitze anzuzeigen. Lines.AddLine() unterstützt BeginArrowHeadStyle nicht – für Pfeile an beiden Enden verwenden Sie TypedLines.AddLine().

Die Ellbogen-Linie verläuft in eine unerwartete Richtung. Ein Ellbogen-Verbinder knickt einmal ab, und die Richtung der Biegung hängt von den Werten für width und height ab. Eine positive Breite mit einer positiven Höhe knickt nach rechts unten ab; ändert man das Vorzeichen eines der beiden Werte, ändert sich die Biegerichtung. Experimentieren Sie zunächst mit kleinen Werten, um die Form zu bestätigen, bevor Sie sich auf ein großes Layout festlegen.

Linien überlappen oder stapeln sich übereinander. Jeder Aufruf von AddLine erzeugt eine unabhängige Form an der angegebenen Position. Wenn zwei Linien dieselbe row und column teilen, überlappen sie sich. Versetzen Sie den row-Wert für jede nachfolgende Linie um 2 oder mehr, wie es das Beispiel tut.

FAQ

Was ist der Unterschied zwischen Lines.AddLine() und TypedLines.AddLine()?

Lines.AddLine() positioniert nach Zeile und Spalte und unterstützt eine Pfeilspitze nur am Ende. TypedLines.AddLine() positioniert nach Pixelkoordinaten und unterstützt Pfeilspitzen an beiden Enden. Für einfache Linienformen ohne Richtungspfeile ist Lines.AddLine() einfacher. Für Verbinder, die eine präzise Platzierung oder bidirektionale Pfeile benötigen, siehe Add Arrow Connectors in Excel in JavaScript (React).

Kann ich eine vertikale Linie erstellen?

Ja. Setzen Sie width auf 1 und height auf einen positiven Wert. Die Linie erstreckt sich vom Ankerpunkt nach unten.

Wie viele Linien kann ein einzelnes Arbeitsblatt enthalten?

In der API gibt es keine feste Grenze. Jede Linie ist ein Formobjekt, das in der Formensammlung des Arbeitsblatts gespeichert ist, und die praktische Einschränkung sind Dateigröße und Rendering-Leistung, wenn Hunderte von Formen vorhanden sind.

Bleiben die Linien erhalten, wenn die Datei in Excel geöffnet wird?

Ja. Linien werden als Standard-Formobjekte im XML des Arbeitsblatts gespeichert. Excel liest und rendert sie nativ – sie sind kein Rendering-Artefakt, das spezifisch für Spire.XLS ist.

Kann ich Linien abrufen und ändern, die bereits in einer Arbeitsmappe vorhanden sind?

Ja. Durchlaufen Sie die Sammlung sheet.Shapes, um auf Linienformobjekte zuzugreifen, und ändern Sie anschließend deren Eigenschaften über die Schnittstelle ILineShape. Zum Löschen verwenden Sie sheet.Shapes.Remove(index).

Siehe auch

• Add Arrow Connectors in Excel in JavaScript (React)
• Integrating Spire.XLS for JavaScript in a React Project
• Spire.XLS for JavaScript Product Page