Inserisci forme di linee in Excel in JavaScript (React)

Un foglio di lavoro non è sempre solo una griglia di numeri. A volte è una tela — un diagramma di flusso abbozzato tra blocchi di dati, un diagramma di relazioni che collega team a progetti, una nota che punta da un'annotazione alla cella che essa commenta. In ognuno di questi casi l'elemento mancante è una linea: un tratto rettilineo tra due caselle, un arco curvo attorno a una regione, un connettore a gomito che si piega una volta e prosegue.

Spire.XLS for JavaScript offre a un'app React il metodo sheet.Lines.AddLine() per inserire forme di linea in una posizione specificata, con quattro tipi di linea disponibili tramite l'enum LineShapeType e il pieno controllo su stile del tratteggio, colore e spessore. Tutto viene eseguito nel browser su WebAssembly — nessun backend, nessuna automazione di Excel, nessun caricamento di file.

Per la configurazione del progetto, consulta Integrating Spire.XLS for JavaScript in a React Project. Gli esempi seguenti presuppongono che il pacchetto sia installato e che il modulo WebAssembly sia stato inizializzato.

Quando un foglio di lavoro ha bisogno di linee

Le linee in un foglio di lavoro servono tre scopi generali, e il tipo di linea da utilizzare dipende da quale di essi ti trovi di fronte:

Il caso della punta di freccia — in cui la linea deve mostrare la direzione — utilizza un'API diversa, TypedLines.AddLine(), che supporta stili di freccia su entrambe le estremità e un posizionamento preciso al pixel. Questo è trattato separatamente in Add Arrow Connectors in Excel in JavaScript (React). Questo articolo si concentra su Lines.AddLine(), che gestisce le quattro forme di linea principali e la loro stilizzazione visiva.

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 per la misurazione del testo e salva con il flag della versione Excel 2010.

I quattro tipi di linea

LineShapeType espone quattro forme, e la differenza tra esse è geometrica — come la linea si sposta dal suo inizio alla sua fine:

Tutte e quattro vengono create dallo stesso metodo — sheet.Lines.AddLine() — con il parametro lineShapeType che seleziona quale viene disegnata. Le proprietà di aspetto (DashStyle, Color, Weight) si applicano uniformemente a tutte e quattro.

Inserire linee in un foglio di lavoro

L'esempio inserisce uno di ciascun tipo di linea in un nuovo foglio di lavoro, ognuno con uno stile di tratteggio e un colore distinti in modo che le quattro forme siano distinguibili nell'output. I passaggi sono:

1. Creare un oggetto Workbook e ottenere il primo foglio di lavoro.
2. Chiamare Worksheet.Lines.AddLine() quattro volte, passando i parametri di posizione e un diverso LineShapeType ogni volta.
3. Personalizzare DashStyle, Color e Weight di ciascuna linea.
4. Salvare la cartella di lavoro con Workbook.SaveToFile().

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;

Quattro tipi di linea inseriti in un foglio di lavoro: retta, curva, a gomito e invertita

La prima linea imposta anche EndArrowHeadStyle, che le conferisce una punta di freccia all'estremità finale — Lines.AddLine() supporta un singolo stile di freccia all'estremità finale, ma non all'inizio. Per frecce su entrambe le estremità o un posizionamento preciso al pixel, usa invece TypedLines.AddLine(), trattato in Add Arrow Connectors in Excel in JavaScript (React).

Personalizzare l'aspetto delle linee

Tre proprietà controllano l'aspetto di una linea, e sono indipendenti — modificarne una non reimposta le altre:

Lo stile del tratteggio è quello che vale la pena sperimentare. Una linea continua si legge come una connessione permanente; una linea punteggiata si legge come provvisoria o opzionale; una linea tratteggiata si legge come un confine. In un diagramma di flusso in cui alcune connessioni sono condizionali, usare Solid per il flusso principale e Dashed per i rami condizionali comunica la distinzione senza una legenda.

Posizionamento per riga e colonna

Lines.AddLine() posiziona una linea usando coordinate di riga e colonna, più una larghezza e un'altezza:

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

• row e column impostano il punto di ancoraggio — dove inizia la linea.
• width imposta l'estensione orizzontale in pixel.
• height imposta l'estensione verticale in pixel. Un'altezza di 1 produce una linea orizzontale; una larghezza di 1 produce una linea verticale.

Questo è un sistema ibrido: l'ancoraggio è in unità del foglio di calcolo (righe e colonne), ma la dimensione è in pixel. Ciò rende semplice allineare una linea a una cella specifica — passa la riga e la colonna di quella cella — ma la lunghezza deve tenere conto delle larghezze delle colonne e delle altezze delle righe, che variano. Se hai bisogno del pieno controllo in pixel sia sulla posizione iniziale che sulla dimensione, TypedLines.AddLine() offre Top e Left in pixel.

Problemi comuni

La linea non è visibile nell'output. Controlla Weight e Color. Uno spessore di 0 o un colore che corrisponde allo sfondo producono una linea invisibile. Verifica anche che row e column collochino la linea all'interno dell'intervallo utilizzato del foglio di lavoro — una linea ancorata alla riga 1000 su un foglio vuoto viene disegnata ma fuori dallo schermo.

Manca la punta di freccia. EndArrowHeadStyle non è stato impostato, oppure è stato impostato a LineNoArrow. Assegna ShapeArrowStyleType.LineArrow per mostrare una punta di freccia all'estremità della linea. Lines.AddLine() non supporta BeginArrowHeadStyle — per frecce su entrambe le estremità, usa TypedLines.AddLine().

La linea a gomito va in una direzione inaspettata. Un connettore a gomito si piega una volta, e la direzione della piega dipende dai valori di width e height. Una larghezza positiva con un'altezza positiva si piega verso il basso a destra; cambiare il segno di uno dei due valori cambia la direzione della piega. Sperimenta prima con valori piccoli per confermare la forma prima di impegnarti in un layout grande.

Le linee si sovrappongono o si impilano l'una sull'altra. Ogni chiamata a AddLine crea una forma indipendente nella posizione specificata. Se due linee condividono la stessa row e column, si sovrappongono. Sfalsa il valore di row di 2 o più per ogni linea successiva, come fa l'esempio.

Domande frequenti

Qual è la differenza tra Lines.AddLine() e TypedLines.AddLine()?

Lines.AddLine() posiziona per riga e colonna e supporta una punta di freccia solo all'estremità finale. TypedLines.AddLine() posiziona per coordinate in pixel e supporta punte di freccia su entrambe le estremità. Per forme di linea di base senza frecce direzionali, Lines.AddLine() è più semplice. Per connettori che richiedono un posizionamento preciso o frecce bidirezionali, consulta Add Arrow Connectors in Excel in JavaScript (React).

Posso creare una linea verticale?

Sì. Imposta width a 1 e height a un valore positivo. La linea si estende verso il basso dal punto di ancoraggio.

Quante linee può contenere un singolo foglio di lavoro?

Non c'è un limite rigido nell'API. Ogni linea è un oggetto forma memorizzato nella raccolta di forme del foglio di lavoro, e il vincolo pratico è la dimensione del file e le prestazioni di rendering quando sono presenti centinaia di forme.

Le linee sopravvivono se il file viene aperto in Excel?

Sì. Le linee vengono memorizzate come oggetti forma standard nell'XML del foglio di lavoro. Excel le legge e le renderizza nativamente — non sono un artefatto di rendering specifico di Spire.XLS.

Posso recuperare e modificare linee già esistenti in una cartella di lavoro?

Sì. Attraversa la raccolta sheet.Shapes per accedere agli oggetti forma di linea, quindi modifica le loro proprietà tramite l'interfaccia ILineShape. Per l'eliminazione, usa sheet.Shapes.Remove(index).

Vedi anche

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