Rendre les données Excel visuelles avec la mise en forme conditionnelle en JavaScript

Un tableau de ventes comportant vingt colonnes de chiffres est exact et illisible. L'œil ne peut pas comparer 43 210 à 38 900 sur une ligne assez rapidement pour repérer le trimestre faible, et la personne qui lit le rapport le sait — c'est pourquoi elle demande un graphique. Mais un graphique par colonne signifie vingt graphiques, et la feuille de calcul devient une galerie plutôt qu'un tableau.

Les barres de données, les échelles de couleurs et les jeux d'icônes résolvent ce problème à l'intérieur même des cellules. Une barre s'allonge proportionnellement à la valeur. Une couleur passe du pâle au saturé à mesure que le nombre augmente. Une icône change de forme lorsque la valeur franchit un seuil. Aucun d'eux n'ajoute de lignes, de colonnes ou d'objets flottants — la visualisation se trouve dans la cellule qui contient déjà le nombre. Tous trois sont des formes de mise en forme conditionnelle Excel, et Spire.XLS for JavaScript les applique via une API unique dans le navigateur sur WebAssembly, les fichiers circulant dans un système de fichiers virtuel (VFS) et sans nécessiter de backend.

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

Pourquoi ne pas simplement ajouter un graphique

Les graphiques et la visualisation dans les cellules répondent à la même question — "comment ces valeurs se comparent-elles ?" — mais ils conviennent à des moments différents :

Lorsque l'objectif est de rendre un tableau de chiffres facile à parcourir sans reconstruire la mise en page, la visualisation dans les cellules est l'outil le plus léger. Les trois sections ci-dessous couvrent chaque type, et ils partagent plus d'API qu'ils n'en diffèrent — ce qui est la première chose à savoir.

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 et un fichier de données de ventes dans le VFS, et enregistre avec l'indicateur de version Excel 2010, qui est la version la plus ancienne prenant en charge ces types de mise en forme conditionnelle.

Une seule API, trois visualisations

Les trois types suivent la même chaîne d'appels. La seule ligne qui change est l'attribution de FormatType :

sheet.ConditionalFormats.Add()  →  xcfs.AddRange(range)  →  format = xcfs.AddCondition()  →  format.FormatType = ???

C'est cette chaîne commune qui explique la ressemblance des trois exemples de code ci-dessous — il s'agit de la même opération avec un type de format différent. Les différences résident dans ce que chaque type produit et dans le moment où vous y feriez appel, ce que le tableau comparatif plus loin dans cet article aborde.

Barres de données : l'ampleur en un coup d'œil

Une barre de données dessine une bande colorée horizontale à l'intérieur de chaque cellule, et la longueur de la bande est proportionnelle à la valeur de la cellule par rapport au reste de la plage sélectionnée. La valeur la plus élevée remplit la cellule ; la plus faible n'en remplit qu'un filet. Parcourir une ligne de barres de données est la même opération mentale que parcourir un graphique à barres, à ceci près que les chiffres restent visibles en dessous.

Les étapes sont les suivantes :

1. Chargez la police et le fichier de données de test dans le VFS.
2. Chargez le classeur et récupérez la feuille de calcul.
3. Appelez ConditionalFormats.Add pour créer une mise en forme conditionnelle, et liez la plage de données avec AddRange.
4. Appelez AddCondition pour ajouter une condition, définissez FormatType sur DataBar et définissez la couleur de la barre.
5. Enregistrez le classeur.

function App() {
  const applyDataBars = 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 and the test data file into the VFS
    await window.spire.FetchFileToVFS('ARIAL.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
    const inputFileName = 'SalesData.xlsx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}data/`);

    // Load the workbook and get the first worksheet
    const workbook = new xlsModule.Workbook();
    workbook.LoadFromFile({ fileName: inputFileName });
    const sheet = workbook.Worksheets.get(0);

    // Select the data range that receives the data bars
    const dataRange = sheet.Range.get("B2:E9");

    // Create a conditional format and bind it to that range
    const xcfs = sheet.ConditionalFormats.Add();
    xcfs.AddRange(dataRange);

    // Add a data bar condition and set the bar color
    const format = xcfs.AddCondition();
    format.FormatType = xlsModule.ConditionalFormatType.DataBar;
    format.DataBar.BarColor = xlsModule.Color.get_CadetBlue();

    // Save the workbook
    const outputFileName = "ApplyDataBars.xlsx";
    workbook.SaveToFile({ fileName: outputFileName, version: xlsModule.ExcelVersion.Version2010 });

    // Dispose of the workbook object to free resources
    workbook.Dispose();

    // Read the result 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>Apply Data Bars</h1>
      <button onClick={applyDataBars}>Start</button>
    </div>
  );
}

export default App;

Barres de données appliquées à un tableau de chiffres de ventes, longueur de barre proportionnelle à la valeur de la cellule

Seules les cellules numériques reçoivent des barres — les cellules de texte à l'intérieur de la plage sont ignorées. C'est normal : une barre de données exprime une magnitude relative, et le texte n'a pas de magnitude à exprimer. Gardez la plage délimitée par la zone numérique ; inclure une colonne de noms de produits ou une ligne d'en-tête ne provoque pas d'erreur, mais ces cellules n'afficheront rien.

Échelles de couleurs : cartographie thermique sans graphique

Une échelle de couleurs ombre chaque cellule en fonction de la position de sa valeur entre le minimum et le maximum de la plage. Aucun argument de couleur n'est requis — lorsqu'aucun n'est spécifié, le résultat est une échelle à deux couleurs qui prend l'orange au minimum et le jaune pâle au maximum, les valeurs intermédiaires étant ombrées proportionnellement. L'effet est une carte thermique intégrée au tableau de données : les points chauds et les points froids sont visibles sans tri ni graphique.

Les étapes sont les mêmes que pour les barres de données, avec FormatType défini sur ColorScale et aucune propriété supplémentaire :

1. Chargez la police et le fichier de données de test dans le VFS.
2. Chargez le classeur et récupérez la feuille de calcul.
3. Appelez ConditionalFormats.Add pour créer une mise en forme conditionnelle, et liez la plage de données avec AddRange.
4. Appelez AddCondition pour ajouter une condition, et définissez FormatType sur ColorScale.
5. Enregistrez le classeur.

function App() {
  const applyColorScales = 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 and the test data file into the VFS
    await window.spire.FetchFileToVFS('ARIAL.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
    const inputFileName = 'SalesData.xlsx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}data/`);

    // Load the workbook and get the first worksheet
    const workbook = new xlsModule.Workbook();
    workbook.LoadFromFile({ fileName: inputFileName });
    const sheet = workbook.Worksheets.get(0);

    // Select the data range that receives the color scales
    const dataRange = sheet.Range.get("B2:E9");

    // Create a conditional format and bind it to that range
    const xcfs = sheet.ConditionalFormats.Add();
    xcfs.AddRange(dataRange);

    // Add a color scale condition; colors transition with the values
    const format = xcfs.AddCondition();
    format.FormatType = xlsModule.ConditionalFormatType.ColorScale;

    // Save the workbook
    const outputFileName = "ApplyColorScales.xlsx";
    workbook.SaveToFile({ fileName: outputFileName, version: xlsModule.ExcelVersion.Version2010 });

    // Dispose of the workbook object to free resources
    workbook.Dispose();

    // Read the result 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>Apply Color Scales</h1>
      <button onClick={applyColorScales}>Start</button>
    </div>
  );
}

export default App;

Échelles de couleurs appliquées à un tableau de chiffres de ventes, dégradé de l'orange au jaune pâle

Là où les barres de données montrent la magnitude absolue par la longueur de la barre, les échelles de couleurs montrent la position relative par la teinte. Une valeur au milieu de la plage obtient une teinte intermédiaire, que la plage s'étende de 1 à 100 ou de 10 000 à 50 000 — l'ombrage est positionnel, non absolu.

Jeux d'icônes : bandes de statut

Un jeu d'icônes place une icône différente dans chaque cellule selon la bande dans laquelle tombe la valeur. L'exemple utilise des feux tricolores : rouge pour le tiers le plus bas, jaune pour le milieu, vert pour le plus élevé. Contrairement aux barres de données et aux échelles de couleurs, qui communiquent un dégradé continu, les jeux d'icônes communiquent une catégorie discrète — "c'est faible", "c'est moyen", "c'est élevé" — ce qui se rapproche davantage d'un indicateur de statut que d'une mesure.

Les étapes ne diffèrent que par le FormatType et la sélection du style d'icône :

1. Chargez la police et le fichier de données de test dans le VFS.
2. Chargez le classeur et récupérez la feuille de calcul.
3. Appelez ConditionalFormats.Add pour créer une mise en forme conditionnelle, et liez la plage de données avec AddRange.
4. Appelez AddCondition pour ajouter une condition, définissez FormatType sur IconSet et spécifiez le type de jeu d'icônes.
5. Enregistrez le classeur.

function App() {
  const applyIconSets = 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 and the test data file into the VFS
    await window.spire.FetchFileToVFS('ARIAL.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/font/`);
    const inputFileName = 'SalesData.xlsx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}data/`);

    // Load the workbook and get the first worksheet
    const workbook = new xlsModule.Workbook();
    workbook.LoadFromFile({ fileName: inputFileName });
    const sheet = workbook.Worksheets.get(0);

    // Select the data range that receives the icon sets
    const dataRange = sheet.Range.get("B2:E9");

    // Create a conditional format and bind it to that range
    const xcfs = sheet.ConditionalFormats.Add();
    xcfs.AddRange(dataRange);

    // Add an icon set condition and set the icon style to three traffic lights
    const format = xcfs.AddCondition();
    format.FormatType = xlsModule.ConditionalFormatType.IconSet;
    format.IconSet.IconSetType = xlsModule.IconSetType.ThreeTrafficLights1;

    // Save the workbook
    const outputFileName = "ApplyIconSets.xlsx";
    workbook.SaveToFile({ fileName: outputFileName, version: xlsModule.ExcelVersion.Version2010 });

    // Dispose of the workbook object to free resources
    workbook.Dispose();

    // Read the result 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>Apply Icon Sets</h1>
      <button onClick={applyIconSets}>Start</button>
    </div>
  );
}

export default App;

Jeux d'icônes appliqués à un tableau de chiffres de ventes, icônes de feux tricolores basées sur des bandes de valeurs

Un jeu d'icônes divise la plage en bandes, de sorte que la même icône couvre une étendue de valeurs différente selon la plage. Dans une plage de 10 à 90, l'icône verte couvre environ 60 à 90 ; dans une plage de 10 à 900, elle couvre environ 600 à 900. Les bandes sont relatives, non absolues — ce qui est la valeur par défaut appropriée pour un tableau où chaque colonne a sa propre échelle, mais qu'il vaut mieux connaître si vous attendez un seuil fixe.

Choisir entre les trois

Les trois s'appliquent à une plage, les trois résident à l'intérieur des cellules et les trois relèvent de la mise en forme conditionnelle. Le choix dépend de ce que le lecteur doit faire des chiffres :

Les trois ne sont pas mutuellement exclusifs. Une feuille de calcul peut porter des barres de données sur les colonnes de chiffre d'affaires et des jeux d'icônes sur la colonne de taux de croissance dans le même enregistrement, car chaque appel à ConditionalFormats.Add crée un format indépendant lié à sa propre plage.

Personnaliser l'apparence des barres de données

La couleur de remplissage d'une barre de données provient de DataBar.BarColor. Définir uniquement FormatType sans BarColor produit le bleu par défaut. Une bordure est également disponible, mais elle a une dépendance : le type de bordure doit être défini avant que la couleur de bordure ne prenne effet.

// Set the border type first so that the border color takes effect
format.DataBar.BarBorder.Type = xlsModule.DataBarBorderType.DataBarBorderSolid;
format.DataBar.BarBorder.Color = xlsModule.Color.get_Red();

// Fill color of the bar
format.DataBar.BarColor = xlsModule.Color.get_GreenYellow();

Définir BarBorder.Color seul, sans définir d'abord BarBorder.Type, n'a aucun effet — la bordure n'est pas dessinée car aucun type de bordure n'a été déclaré. Les échelles de couleurs et les jeux d'icônes n'ont pas de propriétés d'apparence équivalentes ; leur style est déterminé par le type de format et, pour les jeux d'icônes, par l'énumération IconSetType.

Problèmes courants

Les cellules de texte dans la plage cible n'affichent aucune barre de données. C'est normal. Une barre de données exprime une magnitude relative, et seules les cellules numériques ont une magnitude. Les cellules de texte sont ignorées silencieusement — aucune erreur, aucune barre. Limitez la plage à la zone numérique.

Les barres de données sont toutes du bleu par défaut. DataBar.BarColor n'a pas été défini après l'attribution de FormatType. Définissez-le sur n'importe quelle valeur xlsModule.Color pour modifier le remplissage.

La couleur de bordure de la barre de données ne s'affiche pas. Le type de bordure n'a pas été défini en premier. Attribuez DataBar.BarBorder.Type avant DataBar.BarBorder.Color — la couleur ne prend effet qu'une fois un type de bordure pleine déclaré.

Aucun changement visible après l'application d'une mise en forme conditionnelle. Vérifiez que la plage transmise à AddRange correspond à l'emplacement réel des données. Une plage pointant vers des cellules vides ne produit ni erreur ni résultat visible.

FAQ

Puis-je appliquer plusieurs mises en forme conditionnelles à la même plage ?

Oui. Chaque appel à ConditionalFormats.Add crée un format indépendant. Deux formats peuvent cibler la même plage, bien que le résultat visuel de la superposition d'une barre de données et d'une échelle de couleurs sur les mêmes cellules puisse être déroutant — il est généralement plus clair d'appliquer différents types à différentes plages.

Quelles versions d'Excel prennent en charge ces types de mise en forme conditionnelle ?

Les barres de données, les échelles de couleurs et les jeux d'icônes ont été introduits dans Excel 2007. L'exemple enregistre avec ExcelVersion.Version2010 pour garantir la compatibilité avec Excel 2010 et les versions ultérieures.

Ai-je besoin d'Excel installé pour appliquer une mise en forme conditionnelle ?

Non. Le moteur de feuille de calcul est fourni avec le paquet et s'exécute en WebAssembly dans le navigateur. La mise en forme conditionnelle est écrite en XML standard à l'intérieur du fichier .xlsx, et Excel la restitue à l'ouverture du fichier.

Puis-je définir des seuils personnalisés pour les jeux d'icônes ?

L'énumération IconSetType sélectionne un style d'icône prédéfini avec des limites de bandes prédéfinies. L'exemple utilise ThreeTrafficLights1, qui divise la plage en trois bandes égales.

La mise en forme conditionnelle survit-elle si le fichier est ouvert puis réenregistré dans Excel ?

Oui. La mise en forme conditionnelle fait partie des règles de format stockées dans la feuille de calcul, et non d'un artefact de rendu. Excel lit, préserve et réapplique les mêmes règles lors du recalcul.

Voir aussi

• Intégrer Spire.XLS for JavaScript dans un projet React
• Page produit de Spire.XLS for JavaScript