Ajouter des connecteurs fléchés dans Excel en JavaScript (React)

Une ligne entre deux boîtes dans un organigramme dit « ces éléments sont liés ». Une flèche de l'une vers l'autre dit « celui-ci vient en premier ». Cette distinction — la direction — est ce qui sépare un connecteur d'une décoration, et c'est précisément ce que l'API de base Lines.AddLine() ne peut pas faire aux deux extrémités. Un flux de processus a besoin d'une flèche partant de chaque étape ; un diagramme de cause à effet a besoin de flèches pointant vers l'intérieur ; une comparaison nécessite parfois des flèches à double sens pour montrer un lien bidirectionnel. Aucun de ces cas n'est possible avec un seul EndArrowHeadStyle.

Spire.XLS for JavaScript fournit sheet.TypedLines.AddLine() exactement pour ce cas. Il positionne les lignes par coordonnées en pixels plutôt que par ligne et colonne, et il accepte BeginArrowHeadStyle et EndArrowHeadStyle indépendamment — ainsi une ligne peut porter une flèche à une extrémité, aux deux extrémités, ou à aucune. Le moteur s'exécute dans le navigateur sur WebAssembly, avec des fichiers circulant via un système de fichiers virtuel (VFS) et sans backend impliqué.

Pour la configuration du projet, voir 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é.

La direction change tout

Trois diagrammes, trois exigences directionnelles différentes, et la même API de ligne gère les trois :

Le style de pointe de flèche lui-même porte aussi une signification. Une flèche pleine et remplie (LineArrow) se lit comme une connexion définitive et engagée. Une flèche ouverte (LineArrowOpen) se lit comme une connexion plus souple et moins certaine — courante dans les diagrammes de flux de données où la direction est connue mais le mécanisme n'est pas spécifié.

Prérequis

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

TypedLines vs Lines : quelle différence

sheet.Lines.AddLine() et sheet.TypedLines.AddLine() sont deux API distinctes pour deux besoins distincts. Les différences sont structurelles, non cosmétiques :

La prise en charge de la flèche au début est la différence la plus importante. Avec Lines.AddLine(), une ligne peut avoir une pointe de flèche à sa fin mais pas à son début — ce qui suffit pour un flux unidirectionnel mais pas pour un lien bidirectionnel. TypedLines.AddLine() supprime cette contrainte.

Pour les formes de lignes de base sans flèches, Insérer des formes de lignes dans Excel en JavaScript (React) couvre l'API Lines.AddLine().

Positionnement au pixel près

TypedLines.AddLine() place les lignes à l'aide de Top et Left en pixels, avec Width et Height contrôlant l'étendue :

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 de 0 produit une ligne horizontale ; un Width de 0 produit une ligne verticale. Définir les deux à des valeurs non nulles produit une diagonale ou un connecteur coudé, selon le LineShapeType.

Le passage des lignes et colonnes aux coordonnées en pixels importe surtout lorsque les lignes doivent relier des points précis à l'intérieur des cellules — le milieu d'une plage fusionnée, le bord d'une bordure — plutôt que de s'aligner sur les limites des cellules. Le positionnement en pixels vous permet de calculer le début et la fin exacts à partir de la disposition que vous connaissez, plutôt que d'estimer quelle ligne et quelle colonne s'en approche le plus.

Combinaisons de flèches

Avec BeginArrowHeadStyle et EndArrowHeadStyle définis indépendamment, quatre combinaisons couvrent les cas courants :

Le style de flèche peut aussi être LineArrowOpen — une forme de V ouverte plutôt qu'un triangle rempli — à l'une ou l'autre extrémité. Mélanger les styles aux deux extrémités est valide : une flèche remplie à une extrémité et une flèche ouverte à l'autre indiquent qu'une direction est définitive et l'autre incertaine.

Insérer des lignes à pointe de flèche

L'exemple insère six lignes à pointe de flèche dans une nouvelle feuille de calcul, couvrant les combinaisons courantes : une ligne à double flèche, une ligne à flèche unique, un connecteur coudé à flèche, un connecteur coudé à double flèche, un connecteur courbe à flèche, et un connecteur courbe à double flèche. Les étapes sont :

1. Créer un objet Workbook et obtenir la première feuille de calcul.
2. Appeler Worksheet.TypedLines.AddLine() pour créer chaque ligne.
3. Définir la position de la ligne via Top, Left, Width et Height (en pixels).
4. Définir les styles de flèches aux deux extrémités via BeginArrowHeadStyle et EndArrowHeadStyle.
5. Spécifier le type de ligne via LineShapeType (droite, coudée, courbe, etc.).
6. Enregistrer le classeur avec 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;

Six lignes à pointe de flèche : double flèche, flèche unique, flèche coudée, double flèche coudée, flèche courbe et double flèche courbe

Notez la réutilisation des variables line3 et line2 dans la seconde moitié de la fonction. Chaque appel à TypedLines.AddLine() renvoie un nouvel objet ligne qui a déjà été ajouté à la feuille de calcul — la variable est un descripteur pour définir des propriétés, non un conteneur à conserver. Réutiliser le nom de variable pour la ligne suivante est sans risque car la ligne précédente est déjà engagée dans la collection de formes de la feuille.

Gérer les lignes existantes

Une feuille de calcul qui contient déjà des lignes — qu'elles aient été ajoutées par votre code, importées depuis un fichier ou dessinées par un utilisateur — les expose via la collection sheet.Shapes. Chaque forme peut être récupérée par index et modifiée via ses propriétés :

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

Pour la suppression, sheet.Shapes.Remove(index) supprime la forme à l'index spécifié. Pour supprimer des lignes de manière sélective — par nom, par type ou par position — parcourez la collection et supprimez les formes correspondantes. Supprimez depuis le dernier index vers le premier lors d'une suppression en boucle, car la suppression d'un élément décale les index de tous les éléments suivants.

Problèmes courants

La pointe de flèche ne s'affiche pas. BeginArrowHeadStyle ou EndArrowHeadStyle n'a pas été défini, ou a été défini sur LineNoArrow. Vérifiez à quelle extrémité vous attendez la flèche et attribuez la propriété correspondante. Une ligne dont aucune des deux propriétés n'est définie n'a aucune flèche à ses extrémités.

La ligne apparaît à la mauvaise position. Top et Left sont en pixels, pas en lignes et colonnes. Une valeur de Top = 10 place la ligne à 10 pixels du haut de la feuille, pas sur la ligne 10. Si vous êtes habitué à l'API Lines.AddLine(), c'est la source la plus fréquente de mauvais placement.

Le connecteur coudé se plie dans la mauvaise direction. La direction du coude dépend des signes et des magnitudes relatives de Width et Height. Un Width positif avec un Height positif plie vers le bas à droite. Inversez le signe ou échangez les deux valeurs pour changer le coude. Testez d'abord avec de petites valeurs.

La ligne courbe ne se courbe pas comme je l'attendais. Une CurveLine via TypedLines dessine un arc lisse entre les points de début et de fin, et la forme de l'arc est influencée par Width et Height. Contrairement à un connecteur coudé, qui a un seul virage à angle droit, une courbe est continue — mais son tracé exact dépend des dimensions, alors vérifiez le rendu avant de vous y fier pour une disposition précise.

FAQ

Quelle est la différence entre LineArrow et LineArrowOpen ?

LineArrow dessine une pointe de flèche triangulaire remplie. LineArrowOpen dessine une pointe de flèche ouverte en forme de V — deux traits sans remplissage. Le style ouvert est courant dans les diagrammes de flux de données et d'entité-relation où la flèche indique la direction sans impliquer un mécanisme spécifique.

Puis-je définir différents styles de flèches aux deux extrémités ?

Oui. BeginArrowHeadStyle et EndArrowHeadStyle sont des propriétés indépendantes. Une ligne avec LineArrow à une extrémité et LineArrowOpen à l'autre est valide et indique qu'une direction est définitive tandis que l'autre est incertaine.

Quel est le rapport entre les coordonnées en pixels et la disposition de la feuille de calcul ?

Les coordonnées en pixels sont mesurées à partir du coin supérieur gauche de la feuille de calcul. Les hauteurs de lignes et les largeurs de colonnes dans Excel sont mesurées respectivement en points et en caractères, donc convertir entre positions de cellules et coordonnées en pixels nécessite de tenir compte des hauteurs de lignes et largeurs de colonnes actuelles. Pour les lignes qui doivent s'aligner sur les limites des cellules, Lines.AddLine() avec des paramètres de lignes et colonnes peut être plus simple.

Puis-je mélanger Lines.AddLine() et TypedLines.AddLine() dans la même feuille de calcul ?

Oui. Les deux API ajoutent des formes à la collection de formes de la même feuille de calcul. Une feuille de calcul peut contenir simultanément des formes de lignes de base et des lignes à pointe de flèche.

Cela nécessite-t-il qu'Excel soit installé ?

Non. Le moteur s'exécute en WebAssembly dans le navigateur. Les lignes et les flèches sont écrites comme objets de forme standard dans le XML de la feuille de calcul, et Excel les rend nativement lorsque le fichier est ouvert.

Voir aussi

• Insérer des formes de lignes dans Excel en JavaScript (React)
• Intégrer Spire.XLS for JavaScript dans un projet React
• Page produit Spire.XLS for JavaScript