Pfeilverbindungen in Excel mit JavaScript (React) hinzufügen

Eine Linie zwischen zwei Kästen in einem Flussdiagramm besagt „diese stehen in Beziehung zueinander“. Ein Pfeil von einem zum anderen besagt „dieser kommt zuerst“. Diese Unterscheidung – die Richtung – ist es, was eine Verbindungslinie von einer Dekoration trennt, und sie ist genau das, was die grundlegende Lines.AddLine()-API an beiden Enden nicht leisten kann. Ein Prozessablauf benötigt einen Pfeil, der jeden Schritt verlässt; ein Ursache-Wirkungs-Diagramm benötigt Pfeile, die darauf zeigen; ein Vergleich benötigt manchmal Doppelpfeile, um eine bidirektionale Verbindung darzustellen. Nichts davon ist mit einem einzigen EndArrowHeadStyle möglich.

Spire.XLS for JavaScript bietet sheet.TypedLines.AddLine() genau für diesen Fall. Es positioniert Linien anhand von Pixelkoordinaten statt anhand von Zeilen und Spalten und akzeptiert BeginArrowHeadStyle und EndArrowHeadStyle unabhängig voneinander – so kann eine Linie an einem Ende, an beiden Enden oder an keinem Ende einen Pfeil tragen. Die Engine läuft im Browser auf WebAssembly, wobei Dateien über ein virtuelles Dateisystem (VFS) verarbeitet werden und kein Backend beteiligt ist.

Zur Projekteinrichtung siehe Integrieren von Spire.XLS for JavaScript in ein React-Projekt. Die folgenden Beispiele setzen voraus, dass das Paket installiert und das WebAssembly-Modul initialisiert wurde.

Die Richtung verändert alles

Drei Diagramme, drei unterschiedliche Richtungsanforderungen, und dieselbe Linien-API bewältigt sie alle:

Auch der Pfeilspitzenstil selbst trägt Bedeutung. Ein ausgefüllter massiver Pfeil (LineArrow) wird als definitive, verbindliche Verbindung gelesen. Ein offener Pfeil (LineArrowOpen) wird als lockerere, weniger sichere Verbindung gelesen – üblich in Datenflussdiagrammen, in denen die Richtung bekannt, der Mechanismus aber nicht spezifiziert ist.

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 und speichert mit dem Versionsflag für Excel 2010.

TypedLines vs. Lines: Was ist der Unterschied

sheet.Lines.AddLine() und sheet.TypedLines.AddLine() sind zwei getrennte APIs für zwei getrennte Anforderungen. Die Unterschiede sind struktureller, nicht kosmetischer Natur:

Die Unterstützung von Pfeilen am Anfang ist der folgenreichste Unterschied. Bei Lines.AddLine() kann eine Linie eine Pfeilspitze an ihrem Ende, aber nicht an ihrem Anfang haben – das reicht für einen einseitigen Fluss, aber nicht für eine bidirektionale Verbindung. TypedLines.AddLine() beseitigt diese Einschränkung.

Für grundlegende Linienformen ohne Pfeile behandelt Linienformen in Excel in JavaScript (React) einfügen die Lines.AddLine()-API.

Pixelgenaue Positionierung

TypedLines.AddLine() platziert Linien anhand von Top und Left in Pixeln, wobei Width und Height die Ausdehnung steuern:

let line = sheet.TypedLines.AddLine();
line.Top = 10;     // 10 pixels from the top of the sheet
line.Left = 20;    // 20 pixels from the left
line.Width = 100;  // 100 pixels wide
line.Height = 0;   // 0 height — a horizontal line

Ein Height von 0 erzeugt eine horizontale Linie; ein Width von 0 erzeugt eine vertikale. Werden beide auf Werte ungleich null gesetzt, entsteht eine diagonale oder eine geknickte Verbindungslinie, je nach LineShapeType.

Der Wechsel von Zeilen-und-Spalten- zu Pixelkoordinaten ist vor allem dann wichtig, wenn Linien bestimmte Punkte innerhalb von Zellen verbinden müssen – die Mitte eines verbundenen Bereichs, den Rand einer Umrandung –, anstatt sich an Zellgrenzen auszurichten. Die Pixelpositionierung ermöglicht es Ihnen, den exakten Anfang und das exakte Ende aus dem Ihnen bekannten Layout zu berechnen, anstatt zu schätzen, welche Zeile und Spalte am nächsten kommt.

Pfeilkombinationen

Da BeginArrowHeadStyle und EndArrowHeadStyle unabhängig voneinander festgelegt werden, decken vier Kombinationen die gängigen Fälle ab:

Der Pfeilstil kann an beiden Enden auch LineArrowOpen sein – eine offene V-Form statt eines ausgefüllten Dreiecks. Das Mischen von Stilen an den beiden Enden ist zulässig: ein ausgefüllter Pfeil an einem Ende und ein offener Pfeil am anderen vermittelt, dass eine Richtung definitiv und die andere vorläufig ist.

Linien mit Pfeilspitzen einfügen

Das Beispiel fügt sechs Linien mit Pfeilspitzen in ein neues Arbeitsblatt ein und deckt die gängigen Kombinationen ab: eine Doppelpfeillinie, eine Einzelpfeillinie, eine geknickte Pfeilverbindung, eine geknickte Doppelpfeilverbindung, eine geschwungene Pfeilverbindung und eine geschwungene Doppelpfeilverbindung. Die Schritte sind:

1. Erstellen Sie ein Workbook-Objekt und rufen Sie das erste Arbeitsblatt ab.
2. Rufen Sie Worksheet.TypedLines.AddLine() auf, um jede Linie zu erstellen.
3. Legen Sie die Linienposition über Top, Left, Width und Height fest (in Pixeln).
4. Legen Sie die Pfeilstile an beiden Enden über BeginArrowHeadStyle und EndArrowHeadStyle fest.
5. Geben Sie den Linientyp über LineShapeType an (gerade, geknickt, geschwungen usw.).
6. Speichern Sie die Arbeitsmappe mit Workbook.SaveToFile().

function App() {
  const addArrowLines = 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 double-arrow line - solid blue
    let line = sheet.TypedLines.AddLine();
    line.Top = 10;
    line.Left = 20;
    line.Width = 100;
    line.Height = 0;
    line.Color = xlsModule.Color.get_Blue();
    line.BeginArrowHeadStyle = xlsModule.ShapeArrowStyleType.LineArrow;
    line.EndArrowHeadStyle = xlsModule.ShapeArrowStyleType.LineArrow;

    // Add a single-arrow line - solid red
    let line_1 = sheet.TypedLines.AddLine();
    line_1.Top = 50;
    line_1.Left = 30;
    line_1.Width = 100;
    line_1.Height = 100;
    line_1.Color = xlsModule.Color.get_Red();
    line_1.BeginArrowHeadStyle = xlsModule.ShapeArrowStyleType.LineNoArrow;
    line_1.EndArrowHeadStyle = xlsModule.ShapeArrowStyleType.LineArrow;

    // Add an elbow arrow connector
    let line3 = sheet.TypedLines.AddLine();
    line3.LineShapeType = xlsModule.LineShapeType.ElbowLine;
    line3.Width = 30;
    line3.Height = 50;
    line3.EndArrowHeadStyle = xlsModule.ShapeArrowStyleType.LineArrow;
    line3.Top = 100;
    line3.Left = 50;

    // Add an elbow double-arrow connector
    let line2 = sheet.TypedLines.AddLine();
    line2.LineShapeType = xlsModule.LineShapeType.ElbowLine;
    line2.Width = 50;
    line2.Height = 50;
    line2.EndArrowHeadStyle = xlsModule.ShapeArrowStyleType.LineArrow;
    line2.BeginArrowHeadStyle = xlsModule.ShapeArrowStyleType.LineArrow;
    line2.Left = 120;
    line2.Top = 100;

    // Add a curved arrow connector
    line3 = sheet.TypedLines.AddLine();
    line3.LineShapeType = xlsModule.LineShapeType.CurveLine;
    line3.Width = 30;
    line3.Height = 50;
    line3.EndArrowHeadStyle = xlsModule.ShapeArrowStyleType.LineArrowOpen;
    line3.Top = 100;
    line3.Left = 200;

    // Add a curved double-arrow connector
    line2 = sheet.TypedLines.AddLine();
    line2.LineShapeType = xlsModule.LineShapeType.CurveLine;
    line2.Width = 30;
    line2.Height = 50;
    line2.EndArrowHeadStyle = xlsModule.ShapeArrowStyleType.LineArrowOpen;
    line2.BeginArrowHeadStyle = xlsModule.ShapeArrowStyleType.LineArrowOpen;
    line2.Left = 250;
    line2.Top = 100;

    // Save the workbook
    const outputFileName = 'AddArrowLines.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 Arrow Lines</h1>
      <button onClick={addArrowLines}>Start</button>
    </div>
  );
}

export default App;

Sechs Linien mit Pfeilspitzen: Doppelpfeil, Einzelpfeil, geknickter Pfeil, geknickter Doppelpfeil, geschwungener Pfeil und geschwungener Doppelpfeil

Beachten Sie die Wiederverwendung der Variablen line3 und line2 in der zweiten Hälfte der Funktion. Jeder Aufruf von TypedLines.AddLine() gibt ein neues Linienobjekt zurück, das bereits zum Arbeitsblatt hinzugefügt wurde – die Variable ist ein Handle zum Festlegen von Eigenschaften, kein Container, der erhalten bleiben muss. Die Wiederverwendung des Variablennamens für die nächste Linie ist sicher, da die vorherige Linie bereits in der Formensammlung des Blatts festgeschrieben ist.

Bestehende Linien verwalten

Ein Arbeitsblatt, das bereits Linien enthält – sei es durch Ihren Code hinzugefügt, aus einer Datei importiert oder von einem Benutzer gezeichnet – macht sie über die sheet.Shapes-Sammlung verfügbar. Jede Form kann über den Index abgerufen und über ihre Eigenschaften geändert werden:

// Get the first shape in the worksheet
let shape = sheet.Shapes.get(0);
// Modify its properties — color, dash style, etc.
shape.Color = xlsModule.Color.get_Red();

Zum Löschen entfernt sheet.Shapes.Remove(index) die Form am angegebenen Index. Um Linien selektiv zu entfernen – nach Name, nach Typ oder nach Position –, durchlaufen Sie die Sammlung und entfernen Sie die passenden Formen. Löschen Sie in einer Schleife vom letzten Index abwärts, da das Entfernen eines Elements die Indizes aller nachfolgenden Elemente verschiebt.

Häufige Probleme

Die Pfeilspitze wird nicht angezeigt. BeginArrowHeadStyle oder EndArrowHeadStyle wurde nicht festgelegt oder auf LineNoArrow gesetzt. Prüfen Sie, an welchem Ende Sie den Pfeil erwarten, und weisen Sie die entsprechende Eigenschaft zu. Eine Linie, bei der keine der beiden Eigenschaften festgelegt ist, hat an keinem Ende Pfeile.

Die Linie erscheint an der falschen Position. Top und Left sind in Pixeln angegeben, nicht in Zeilen und Spalten. Der Wert Top = 10 platziert die Linie 10 Pixel vom oberen Rand des Blatts entfernt, nicht in Zeile 10. Wenn Sie die Lines.AddLine()-API gewohnt sind, ist dies die häufigste Ursache für eine Fehlplatzierung.

Die geknickte Verbindungslinie knickt in die falsche Richtung. Die Knickrichtung hängt von den Vorzeichen und den relativen Größen von Width und Height ab. Ein positives Width mit einem positiven Height knickt nach unten rechts. Vertauschen Sie das Vorzeichen oder die beiden Werte, um den Knick zu ändern. Testen Sie zunächst mit kleinen Werten.

Die geschwungene Linie krümmt sich nicht so, wie ich es erwartet habe. Eine CurveLine über TypedLines zeichnet einen glatten Bogen zwischen Start- und Endpunkt, und die Form des Bogens wird von Width und Height beeinflusst. Anders als eine geknickte Verbindungslinie, die einen einzigen rechtwinkligen Knick aufweist, ist eine Kurve kontinuierlich – aber ihr genauer Verlauf hängt von den Abmessungen ab, prüfen Sie also die Ausgabe, bevor Sie sich für ein präzises Layout darauf verlassen.

FAQ

Was ist der Unterschied zwischen LineArrow und LineArrowOpen?

LineArrow zeichnet eine ausgefüllte dreieckige Pfeilspitze. LineArrowOpen zeichnet eine offene V-förmige Pfeilspitze – zwei Striche ohne Füllung. Der offene Stil ist in Datenfluss- und Entity-Relationship-Diagrammen üblich, in denen der Pfeil die Richtung anzeigt, ohne einen bestimmten Mechanismus zu implizieren.

Kann ich an den beiden Enden unterschiedliche Pfeilstile festlegen?

Ja. BeginArrowHeadStyle und EndArrowHeadStyle sind unabhängige Eigenschaften. Eine Linie mit LineArrow an einem Ende und LineArrowOpen am anderen ist zulässig und vermittelt, dass eine Richtung definitiv und die andere vorläufig ist.

Wie stehen Pixelkoordinaten zum Layout des Arbeitsblatts in Beziehung?

Pixelkoordinaten werden von der oberen linken Ecke des Arbeitsblatts aus gemessen. Zeilenhöhen und Spaltenbreiten in Excel werden in Punkten bzw. Zeichen gemessen, sodass für die Umrechnung zwischen Zellpositionen und Pixelkoordinaten die aktuellen Zeilenhöhen und Spaltenbreiten berücksichtigt werden müssen. Für Linien, die an Zellgrenzen ausgerichtet werden müssen, ist Lines.AddLine() mit Zeilen- und Spaltenparametern möglicherweise einfacher.

Kann ich Lines.AddLine() und TypedLines.AddLine() im selben Arbeitsblatt mischen?

Ja. Beide APIs fügen Formen zur Formensammlung desselben Arbeitsblatts hinzu. Ein Arbeitsblatt kann gleichzeitig grundlegende Linienformen und Linien mit Pfeilspitzen enthalten.

Erfordert dies eine installierte Excel-Version?

Nein. Die Engine läuft als WebAssembly im Browser. Linien und Pfeile werden als Standard-Formobjekte in der Arbeitsblatt-XML geschrieben, und Excel rendert sie beim Öffnen der Datei nativ.

Siehe auch

• Linienformen in Excel in JavaScript (React) einfügen
• Integrieren von Spire.XLS for JavaScript in ein React-Projekt
• Produktseite von Spire.XLS for JavaScript