Insérer des formes de ligne dans Excel en JavaScript (React)

Une feuille de calcul n'est pas toujours qu'une simple grille de nombres. Parfois, c'est une toile — un organigramme esquissé entre des blocs de données, un diagramme de relations reliant des équipes à des projets, une légende pointant d'une note vers la cellule qu'elle annote. Dans chacun de ces cas, l'élément manquant est une ligne : un trait droit entre deux cases, un arc courbe autour d'une zone, un connecteur coudé qui plie une fois puis continue.

Spire.XLS for JavaScript offre à une application React la méthode sheet.Lines.AddLine() pour insérer des formes de ligne à une position spécifiée, avec quatre types de lignes disponibles via l'énumération LineShapeType et un contrôle total sur le style de tiret, la couleur et l'épaisseur. Tout s'exécute dans le navigateur sur WebAssembly — pas de backend, pas d'automatisation Excel, pas de téléversement de fichier.

Pour la configuration du projet, consultez Intégrer Spire.XLS for JavaScript dans un projet React. Les exemples ci-dessous supposent que le package est installé et que le module WebAssembly a été initialisé.

Quand une feuille de calcul a besoin de lignes

Les lignes dans une feuille de calcul répondent à trois grands objectifs, et le type de ligne que vous choisissez dépend de celui qui se présente à vous :

Le cas de la pointe de flèche — où la ligne doit indiquer une direction — utilise une API différente, TypedLines.AddLine(), qui prend en charge des styles de flèche aux deux extrémités et un positionnement précis au pixel près. Cela est traité séparément dans Ajouter des connecteurs fléchés dans Excel en JavaScript (React). Cet article se concentre sur Lines.AddLine(), qui gère les quatre formes de ligne principales et leur style visuel.

Prérequis

Vous avez besoin d'un projet React avec Spire.XLS for JavaScript installé et le module WebAssembly initialisé, accessible à window.wasmModule.spirexls. L'exemple charge une police dans le VFS pour la mesure du texte et enregistre avec l'indicateur de version Excel 2010.

Les quatre types de lignes

LineShapeType expose quatre formes, et la différence entre elles est géométrique — la manière dont la ligne se déplace de son début à sa fin :

Les quatre sont créées par la même méthode — sheet.Lines.AddLine() — le paramètre lineShapeType déterminant celle qui est dessinée. Les propriétés d'apparence (DashStyle, Color, Weight) s'appliquent uniformément aux quatre.

Insérer des lignes dans une feuille de calcul

L'exemple insère un exemplaire de chaque type de ligne dans une nouvelle feuille de calcul, chacun avec un style de tiret et une couleur distincts afin que les quatre formes soient reconnaissables dans le résultat. Les étapes sont les suivantes :

1. Créez un objet Workbook et récupérez la première feuille de calcul.
2. Appelez Worksheet.Lines.AddLine() quatre fois, en passant des paramètres de position et un LineShapeType différent à chaque fois.
3. Personnalisez le DashStyle, la Color et le Weight de chaque ligne.
4. Enregistrez le classeur avec 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;

Quatre types de lignes insérés dans une feuille de calcul : droite, courbe, coudée et inversée

La première ligne définit également EndArrowHeadStyle, ce qui lui donne une pointe de flèche à la fin — Lines.AddLine() prend en charge un seul style de flèche à la fin, mais pas au début. Pour des flèches aux deux extrémités ou un positionnement précis au pixel près, utilisez plutôt TypedLines.AddLine(), traité dans Ajouter des connecteurs fléchés dans Excel en JavaScript (React).

Personnaliser l'apparence des lignes

Trois propriétés contrôlent l'apparence d'une ligne, et elles sont indépendantes — modifier l'une ne réinitialise pas les autres :

Le style de tiret est celui qui vaut la peine d'être expérimenté. Une ligne pleine se lit comme une connexion permanente ; une ligne pointillée se lit comme une connexion provisoire ou facultative ; une ligne en tirets se lit comme une limite. Dans un organigramme où certaines connexions sont conditionnelles, utiliser Solid pour le flux principal et Dashed pour les branches conditionnelles communique la distinction sans légende.

Positionnement par ligne et colonne

Lines.AddLine() place une ligne en utilisant des coordonnées de ligne et de colonne, plus une largeur et une hauteur :

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

• row et column définissent le point d'ancrage — là où la ligne commence.
• width définit l'étendue horizontale en pixels.
• height définit l'étendue verticale en pixels. Une hauteur de 1 produit une ligne horizontale ; une largeur de 1 produit une ligne verticale.

Il s'agit d'un système hybride : l'ancre est exprimée en unités de feuille de calcul (lignes et colonnes), mais la taille est en pixels. Cela permet d'aligner facilement une ligne avec une cellule spécifique — passez la ligne et la colonne de cette cellule — mais la longueur doit tenir compte des largeurs de colonnes et des hauteurs de lignes, qui varient. Si vous avez besoin d'un contrôle total au pixel près sur la position de départ ainsi que sur la taille, TypedLines.AddLine() propose Top et Left en pixels.

Problèmes courants

La ligne n'est pas visible dans le résultat. Vérifiez Weight et Color. Une épaisseur de 0 ou une couleur identique à l'arrière-plan produit une ligne invisible. Vérifiez également que row et column placent la ligne dans la plage utilisée de la feuille de calcul — une ligne ancrée à la ligne 1000 sur une feuille vide est dessinée mais hors écran.

La pointe de flèche est absente. EndArrowHeadStyle n'a pas été défini, ou a été défini sur LineNoArrow. Attribuez ShapeArrowStyleType.LineArrow pour afficher une pointe de flèche à la fin de la ligne. Lines.AddLine() ne prend pas en charge BeginArrowHeadStyle — pour des flèches aux deux extrémités, utilisez TypedLines.AddLine().

La ligne coudée va dans une direction inattendue. Un connecteur coudé plie une fois, et la direction du coude dépend des valeurs de width et height. Une largeur positive avec une hauteur positive plie vers le bas à droite ; changer le signe de l'une ou l'autre valeur change la direction du coude. Expérimentez d'abord avec de petites valeurs pour confirmer la forme avant de vous engager dans une grande mise en page.

Les lignes se chevauchent ou s'empilent les unes sur les autres. Chaque appel à AddLine crée une forme indépendante à la position spécifiée. Si deux lignes partagent la même row et la même column, elles se chevauchent. Décalez la valeur de row de 2 ou plus pour chaque ligne successive, comme le fait l'exemple.

FAQ

Quelle est la différence entre Lines.AddLine() et TypedLines.AddLine() ?

Lines.AddLine() positionne par ligne et colonne et ne prend en charge une pointe de flèche qu'à la fin. TypedLines.AddLine() positionne par coordonnées en pixels et prend en charge des pointes de flèche aux deux extrémités. Pour des formes de ligne de base sans flèches directionnelles, Lines.AddLine() est plus simple. Pour des connecteurs nécessitant un placement précis ou des flèches bidirectionnelles, consultez Ajouter des connecteurs fléchés dans Excel en JavaScript (React).

Puis-je créer une ligne verticale ?

Oui. Définissez width sur 1 et height sur une valeur positive. La ligne s'étend vers le bas à partir du point d'ancrage.

Combien de lignes une seule feuille de calcul peut-elle contenir ?

Il n'y a pas de limite stricte dans l'API. Chaque ligne est un objet de forme stocké dans la collection de formes de la feuille de calcul, et la contrainte pratique est la taille du fichier et les performances de rendu lorsque des centaines de formes sont présentes.

Les lignes subsistent-elles si le fichier est ouvert dans Excel ?

Oui. Les lignes sont stockées comme des objets de forme standard dans le XML de la feuille de calcul. Excel les lit et les affiche nativement — ce ne sont pas des artefacts de rendu propres à Spire.XLS.

Puis-je récupérer et modifier des lignes qui existent déjà dans un classeur ?

Oui. Parcourez la collection sheet.Shapes pour accéder aux objets de forme de ligne, puis modifiez leurs propriétés via l'interface ILineShape. Pour la suppression, utilisez sheet.Shapes.Remove(index).

Voir aussi

• Ajouter des connecteurs fléchés dans Excel en JavaScript (React)
• Intégrer Spire.XLS for JavaScript dans un projet React
• Page produit de Spire.XLS for JavaScript