Ajouter des propriétés aux valeurs de base des cellules Excel

Utilisez des propriétés sur une valeur de cellule de base quand vous souhaitez qu’une cellule conserve sa valeur d’origine string, doubleou Boolean et expose également des détails supplémentaires. Par exemple, une facture de restaurant peut conserver un nombre pour les calculs tout en affichant Food, Drinks, Taxet Tip dans le type de données carte et dans les formules.

Cet article explique comment créer une valeur de base avec des propriétés, mettre à jour une valeur existante, mettre en forme des valeurs numériques et ajouter des types de données imbriqués.

• Commencez par Vue d’ensemble des types de données dans les compléments Excel si vous débutez avec les types de données Excel.
• Passez en revue le schéma JSON dans Utiliser des types de données dans les compléments Excel.
• Utilisez Créer des types de données d’entité liée dans les compléments Excel lorsque vos données proviennent d’une source externe et doivent être actualisées indépendamment.

L’exemple suivant montre le nombre 14.67 avec des champs ajoutés nommés Drinks, Food, Taxet Tip.

Lorsque les utilisateurs ouvrent le type de données carte, ils peuvent voir les champs supplémentaires.

Les valeurs de base avec des propriétés peuvent également être référencées dans des formules à l’aide de la notation par points.

Créer une valeur de cellule avec des propriétés

Utilisez Range.valuesAsJson pour créer une valeur et définir ses propriétés dans une seule affectation. L’exemple suivant écrit un nombre dans A1 et ajoute des détails de facture en tant que propriétés.

async function createNumberProperties() {
  await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const range = sheet.getRange("A1");

    range.valuesAsJson = [
      [
        {
          type: Excel.CellValueType.double,
          basicType: Excel.RangeValueType.double,
          basicValue: 14.67,
          properties: {
            Food: {
              type: Excel.CellValueType.string,
              basicType: Excel.RangeValueType.string,
              basicValue: "Sandwich and fries"
            },
            Drinks: {
              type: Excel.CellValueType.string,
              basicType: Excel.RangeValueType.string,
              basicValue: "Soda"
            },
            Tax: {
              type: Excel.CellValueType.double,
              basicType: Excel.RangeValueType.double,
              basicValue: 5.5
            },
            Tip: {
              type: Excel.CellValueType.double,
              basicType: Excel.RangeValueType.double,
              basicValue: 21
            }
          }
        }
      ]
    ];

    await context.sync();
  });
}

Ajouter des propriétés à une valeur existante

Utilisez ce modèle lorsqu’une cellule contient déjà une valeur de base et que vous souhaitez l’enrichir sans modifier son type sous-jacent. Tout d’abord, lisez la valeur à l’aide de valuesAsJson. Vérifiez ensuite que la valeur est un string, doubleou Boolean avant d’ajouter des propriétés.

L’exemple suivant obtient le nombre dans A1, conserve toutes les propriétés existantes et ajoute une Precision propriété .

async function addPropertyToNumber() {
  await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const range = sheet.getRange("A1");

    range.load("valuesAsJson");
    await context.sync();

    const cellValue = range.valuesAsJson[0][0] as any;

    // Only apply this property to a double.
    if (cellValue.basicType === Excel.RangeValueType.double) {
      cellValue.properties = {
        ...(cellValue.properties ?? {}),
        Precision: {
          type: Excel.CellValueType.double,
          basicValue: 4
        }
      };

      range.valuesAsJson = [[cellValue]];
      await context.sync();
    }
  });
}

Choisir une valeur de base ou une valeur d’entité

L’ajout de propriétés aux stringtypes de base , Booleanet double est similaire à l’ajout de propriétés aux valeurs d’entité, mais le comportement est différent de plusieurs manières importantes.

• Utilisez une valeur de base avec des propriétés lorsque les formules doivent continuer à traiter la cellule comme sa valeur sous-jacente. Les types de base n’ayant pas de secours d’erreur, les calculs peuvent toujours continuer. Par exemple, =SUM(A1:A3) retourne 6 toujours si A1 est un double avec des propriétés et A2 et sont A3 des nombres standard.
• Lorsqu’un calcul utilise une valeur de base, le résultat inclut uniquement la valeur sous-jacente. Le résultat ne conserve pas les propriétés sources.
• Si vous ne spécifiez pas d’icône pour une valeur de base, la cellule n’affiche aucune icône. Les valeurs d’entité affichent une icône par défaut lorsqu’aucune icône n’est spécifiée.

Valeurs numériques formatées

Vous pouvez appliquer la mise en forme de nombre à des valeurs de type CellValueType.double à l’aide de la numberFormat propriété . L’exemple suivant crée une valeur monétaire et ajoute une propriété descriptive.

async function createCurrencyValue() {
  await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const range = sheet.getRange("A1");

    range.valuesAsJson = [
      [
        {
          type: Excel.CellValueType.double,
          basicType: Excel.RangeValueType.double,
          basicValue: 24,
          numberFormat: "$0.00",
          properties: {
            Name: {
              type: Excel.CellValueType.string,
              basicValue: "Price"
            }
          }
        }
      ]
    ];

    await context.sync();
  });
}

Ce format de nombre est le format par défaut de la valeur. Si l’utilisateur, ou un autre code, applique un format différent à la cellule, ce format remplace la valeur de numberFormat.

Personnaliser la disposition carte

Les valeurs de base avec des propriétés utilisent un type de données par défaut carte. Pour afficher les propriétés de manière plus utile, ajoutez la layouts propriété à la description JSON et définissez une disposition carte personnalisée.

Pour obtenir des options de disposition et des exemples, consultez Utiliser des cartes avec des types de données de valeur de cellule.

Types de données imbriqués

Vous pouvez imbriquer d’autres types de données à l’intérieur d’une valeur de base, y compris des valeurs d’entité et des valeurs , doubleet Boolean supplémentairesstring. L’exemple suivant écrit une valeur de charge de batterie de l’ordinateur dans A1, puis ajoute une entité imbriquée qui décrit l’ordinateur et ses paramètres d’alimentation.

async function createNumberWithNestedEntity() {
  await Excel.run(async (context) => {
    const sheet = context.workbook.worksheets.getActiveWorksheet();
    const range = sheet.getRange("A1");

    range.valuesAsJson = [
      [
        {
          type: Excel.CellValueType.double,
          basicType: Excel.RangeValueType.double,
          layouts: {
            compact: {
              icon: "Battery10"
            }
          },
          basicValue: 0.7,
          numberFormat: "00%",
          properties: {
            Computer: {
              type: Excel.CellValueType.entity,
              text: "Laptop",
              properties: {
                "Power Consumption": {
                  type: Excel.CellValueType.double,
                  basicType: Excel.RangeValueType.double,
                  basicValue: 0.25,
                  numberFormat: "00%",
                  layouts: {
                    compact: {
                      icon: "Power"
                    }
                  },
                  properties: {
                    Plan: {
                      type: Excel.CellValueType.string,
                      basicType: Excel.RangeValueType.string,
                      basicValue: "Balanced"
                    }
                  }
                },
                Charging: {
                  type: Excel.CellValueType.boolean,
                  basicType: Excel.RangeValueType.boolean,
                  basicValue: true
                }
              }
            }
          }
        }
      ]
    ];

    await context.sync();
  });
}

L’image suivante montre la valeur et le type de données carte pour l’entité d’ordinateur portable imbriqué.

Compatibilité

Sur les versions précédentes d’Excel qui ne prennent pas en charge la fonctionnalité de types de données, les utilisateurs voient un avertissement Type de données indisponible . La valeur apparaît toujours dans la cellule et continue à fonctionner avec les formules et d’autres fonctionnalités Excel. Si la valeur est un nombre mis en forme, les calculs utilisent au basicValue lieu du nombre mis en forme.

Sur les versions d’Excel antérieures à Office 2016, la valeur s’affiche dans la cellule sans erreur et ne peut pas être distinguishable d’une valeur de base.

Voir aussi

• Vue d’ensemble des types de données dans Excel de données
• Utiliser des types de données dans les compléments Excel
• Utiliser des cartes avec des types de données de valeur de cellule
• Créer des types de données d’entité liée dans des compléments Excel