Aggiungi connettori a freccia in Excel in JavaScript (React)

Una linea tra due caselle in un diagramma di flusso dice "queste sono correlate". Una freccia da una all'altra dice "questa viene prima". Questa distinzione — la direzione — è ciò che separa un connettore da una decorazione, ed è l'unica cosa che l'API di base Lines.AddLine() non può fare su entrambe le estremità. Un flusso di processo necessita di una freccia che esce da ogni passaggio; un diagramma causa-effetto necessita di frecce che puntano verso l'interno; un confronto a volte necessita di frecce a doppia punta per mostrare un collegamento bidirezionale. Nessuna di queste è possibile con un singolo EndArrowHeadStyle.

Spire.XLS for JavaScript fornisce sheet.TypedLines.AddLine() esattamente per questo caso. Posiziona le linee tramite coordinate in pixel invece che per riga e colonna, e accetta BeginArrowHeadStyle e EndArrowHeadStyle in modo indipendente — così una linea può avere una freccia su un'estremità, su entrambe o su nessuna. Il motore funziona nel browser su WebAssembly, con i file che passano attraverso un file system virtuale (VFS) e senza alcun backend coinvolto.

Per la configurazione del progetto, vedi Integrazione di Spire.XLS for JavaScript in un progetto React. Gli esempi seguenti presuppongono che il pacchetto sia installato e che il modulo WebAssembly sia stato inizializzato.

La direzione cambia tutto

Tre diagrammi, tre requisiti direzionali diversi, e la stessa API per le linee li gestisce tutti:

Anche lo stile della punta di freccia ha un significato. Una freccia piena e riempita (LineArrow) viene letta come una connessione definita e consolidata. Una freccia aperta (LineArrowOpen) viene letta come una connessione più blanda e meno certa — comune nei diagrammi di flusso dei dati, dove la direzione è nota ma il meccanismo non è specificato.

Prerequisiti

È necessario un progetto React con Spire.XLS for JavaScript installato e il modulo WebAssembly inizializzato, accessibile all'indirizzo window.wasmModule.spirexls. L'esempio carica un font nel VFS e salva con il flag di versione Excel 2010.

TypedLines vs Lines: qual è la differenza

sheet.Lines.AddLine() e sheet.TypedLines.AddLine() sono due API separate per due esigenze separate. Le differenze sono strutturali, non estetiche:

Il supporto della freccia iniziale è la differenza più rilevante. Con Lines.AddLine(), una linea può avere una punta di freccia alla sua estremità finale ma non all'inizio — il che è sufficiente per un flusso unidirezionale ma non per un collegamento bidirezionale. TypedLines.AddLine() elimina questo vincolo.

Per le forme di linea di base senza frecce, Inserire forme di linea in Excel in JavaScript (React) copre l'API Lines.AddLine().

Posizionamento preciso al pixel

TypedLines.AddLine() posiziona le linee usando Top e Left in pixel, con Width e Height che ne controllano l'estensione:

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

Un Height di 0 produce una linea orizzontale; un Width di 0 ne produce una verticale. Impostando entrambi su valori diversi da zero si ottiene una diagonale o un connettore piegato, a seconda del LineShapeType.

Il passaggio da coordinate di riga e colonna a coordinate in pixel è più importante quando le linee devono collegare punti specifici all'interno delle celle — il centro di un intervallo unito, il bordo di una cornice — invece di allinearsi ai confini delle celle. Il posizionamento in pixel consente di calcolare l'inizio e la fine esatti dal layout che si conosce, invece di stimare quale riga e colonna si avvicini di più.

Combinazioni di frecce

Con BeginArrowHeadStyle e EndArrowHeadStyle impostati in modo indipendente, quattro combinazioni coprono i casi più comuni:

Lo stile della freccia può anche essere LineArrowOpen — una forma a V aperta invece di un triangolo pieno — su entrambe le estremità. Mescolare gli stili sulle due estremità è valido: una freccia piena su un'estremità e una freccia aperta sull'altra comunicano che una direzione è definita e l'altra è incerta.

Inserire linee con punta di freccia

L'esempio inserisce sei linee con punta di freccia in un foglio di lavoro nuovo, coprendo le combinazioni più comuni: una linea a doppia freccia, una linea a freccia singola, un connettore a gomito con freccia, un connettore a gomito a doppia freccia, un connettore curvo con freccia e un connettore curvo a doppia freccia. I passaggi sono:

1. Creare un oggetto Workbook e ottenere il primo foglio di lavoro.
2. Chiamare Worksheet.TypedLines.AddLine() per creare ciascuna linea.
3. Impostare la posizione della linea tramite Top, Left, Width e Height (in pixel).
4. Impostare gli stili delle frecce su entrambe le estremità tramite BeginArrowHeadStyle e EndArrowHeadStyle.
5. Specificare il tipo di linea tramite LineShapeType (dritta, a gomito, curva, ecc.).
6. Salvare il workbook con 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;

Sei linee con punta di freccia: doppia freccia, freccia singola, freccia a gomito, doppia freccia a gomito, freccia curva e doppia freccia curva

Si noti il riutilizzo delle variabili line3 e line2 nella seconda metà della funzione. Ogni chiamata a TypedLines.AddLine() restituisce un nuovo oggetto linea che è già stato aggiunto al foglio di lavoro — la variabile è un riferimento per impostare proprietà, non un contenitore che deve essere conservato. Riutilizzare il nome della variabile per la linea successiva è sicuro perché la linea precedente è già stata inserita nella raccolta di forme del foglio.

Gestire le linee esistenti

Un foglio di lavoro che contiene già delle linee — che siano state aggiunte dal tuo codice, importate da un file o disegnate da un utente — le espone tramite la raccolta sheet.Shapes. Ogni forma può essere recuperata tramite indice e modificata attraverso le sue proprietà:

// 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();

Per l'eliminazione, sheet.Shapes.Remove(index) rimuove la forma all'indice specificato. Per rimuovere le linee in modo selettivo — per nome, per tipo o per posizione — iterare la raccolta e rimuovere le forme corrispondenti. Quando si elimina in un ciclo, procedere dall'ultimo indice verso il basso, poiché la rimozione di un elemento sposta gli indici di tutti gli elementi successivi.

Problemi comuni

La punta della freccia non viene visualizzata. BeginArrowHeadStyle o EndArrowHeadStyle non è stato impostato, oppure è stato impostato su LineNoArrow. Verifica su quale estremità ti aspetti la freccia e assegna la proprietà corrispondente. Una linea con nessuna delle due proprietà impostate non ha frecce su nessuna delle estremità.

La linea appare nella posizione sbagliata. Top e Left sono in pixel, non in righe e colonne. Un valore di Top = 10 posiziona la linea a 10 pixel dalla parte superiore del foglio, non sulla riga 10. Se sei abituato all'API Lines.AddLine(), questa è la fonte più comune di posizionamento errato.

Il connettore a gomito si piega nella direzione sbagliata. La direzione della piega dipende dai segni e dalle grandezze relative di Width e Height. Un Width positivo con un Height positivo piega verso il basso a destra. Inverti il segno o scambia i due valori per cambiare la piega. Prova prima con valori piccoli.

La linea curva non si curva come mi aspettavo. Una CurveLine tramite TypedLines disegna un arco uniforme tra i punti di inizio e fine, e la forma dell'arco è influenzata da Width e Height. A differenza di un connettore a gomito, che ha una singola piega ad angolo retto, una curva è continua — ma il suo percorso esatto dipende dalle dimensioni, quindi verifica il risultato prima di affidarti a essa per un layout preciso.

FAQ

Qual è la differenza tra LineArrow e LineArrowOpen?

LineArrow disegna una punta di freccia triangolare piena. LineArrowOpen disegna una punta di freccia aperta a forma di V — due tratti senza riempimento. Lo stile aperto è comune nei diagrammi di flusso dei dati e nei diagrammi entità-relazione, dove la freccia indica la direzione senza implicare un meccanismo specifico.

Posso impostare stili di freccia diversi sulle due estremità?

Sì. BeginArrowHeadStyle e EndArrowHeadStyle sono proprietà indipendenti. Una linea con LineArrow su un'estremità e LineArrowOpen sull'altra è valida e comunica che una direzione è definita mentre l'altra è incerta.

Come si rapportano le coordinate in pixel al layout del foglio di lavoro?

Le coordinate in pixel sono misurate dall'angolo in alto a sinistra del foglio di lavoro. Le altezze di riga e le larghezze di colonna in Excel sono misurate rispettivamente in punti e caratteri, quindi la conversione tra posizioni di cella e coordinate in pixel richiede di tenere conto delle altezze di riga e delle larghezze di colonna correnti. Per le linee che devono allinearsi ai confini delle celle, Lines.AddLine() con parametri di riga e colonna può essere più semplice.

Posso mescolare Lines.AddLine() e TypedLines.AddLine() nello stesso foglio di lavoro?

Sì. Entrambe le API aggiungono forme alla stessa raccolta di forme del foglio di lavoro. Un foglio di lavoro può contenere contemporaneamente forme di linea di base e linee con punta di freccia.

È necessario avere Excel installato?

No. Il motore funziona come WebAssembly nel browser. Le linee e le frecce vengono scritte come oggetti forma standard nell'XML del foglio di lavoro, ed Excel le visualizza nativamente quando il file viene aperto.

Vedi anche

• Inserire forme di linea in Excel in JavaScript (React)
• Integrazione di Spire.XLS for JavaScript in un progetto React
• Pagina del prodotto Spire.XLS for JavaScript