Ajouter des propriétés à des valeurs de cellule de base

Ajoutez des propriétés aux valeurs de cellule de base dans Excel pour associer des informations supplémentaires aux valeurs. Comme pour les valeurs d’entité, vous pouvez ajouter des propriétés aux types de base chaîne, double et booléen . Chaque propriété est une paire clé/valeur. L’exemple suivant montre le nombre 14,67 (un double) qui représente une facture avec des champs ajoutés nommés Boissons, Nourriture, Taxe et Pourboire.

Si l’utilisateur choisit d’afficher le type de données carte, il verra les valeurs des champs.

Les propriétés de valeur de cellule peuvent également être utilisées dans les formules.

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

Pour créer une valeur de cellule et y ajouter des propriétés, utilisez Range.valuesAsJson pour attribuer des propriétés. L’exemple de code suivant montre comment créer un nouveau nombre dans la cellule A1. Il ajoute la nourriture, les boissons et les propriétés supplémentaires décrivant une facture dans un restaurant. Il affecte une description JSON des propriétés à valuesAsJson.

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

Remarque

Certaines valeurs de cellule changent en fonction des paramètres régionaux d’un utilisateur. La propriété valuesAsJsonLocal offre une prise en charge de la localisation et est disponible sur tous les mêmes objets que valuesAsJson.

Ajouter des propriétés à une valeur existante

Pour ajouter des propriétés à une valeur existante, commencez par obtenir la valeur à partir de la cellule à l’aide valuesAsJsonde , puis ajoutez-y un objet JSON de propriétés. L’exemple suivant montre comment obtenir la valeur numérique de la cellule A1 et lui affecter une propriété nommée Precision . Notez que vous devez case activée le type de la valeur pour vous assurer qu’il s’agit d’une chaîne, d’un double ou d’un type de base booléen.

async function addPropertyToNumber() {
    await Excel.run(async (context) => {
        let sheet = context.workbook.worksheets.getActiveWorksheet();
        let range = sheet.getRange("A1");
        range.load("valuesAsJson");
        await context.sync();
        let cellValue = range.valuesAsJson[0][0] as any;

        // Only apply this property to a double.
        if (cellValue.basicType === "Double") {
            cellValue.properties = {
                Precision: {
                    type: Excel.CellValueType.double,
                    basicValue: 4
                }
            };
            range.valuesAsJson = [[cellValue]];
            await context.sync();
        }
    });
}

Différences par rapport aux valeurs d’entité

L’ajout de propriétés aux types string, Boolean et double de base est similaire à l’ajout de propriétés aux valeurs d’entité. Toutefois, il y a des différences.

• Les types de base ont un secours sans erreur afin que les calculs puissent fonctionner sur eux. Par exemple, considérez la formule =SOMME(A1 :A3) où A1 est 1, A2 est 2 et A3 est 3. A1 est un double avec des propriétés, tandis que A2 et A3 n’ont pas de propriétés. La somme retourne le résultat correct de 6. La formule ne fonctionnerait pas si A1 était une valeur d’entité.
• Lorsque la valeur d’un type de base est utilisée dans un calcul, les propriétés sont exclues dans le résultat. Dans l’exemple précédent de =SOMME(A1 :A3), où A1 est un double avec des propriétés, le résultat de 6 n’a aucune propriété.
• Si aucune icône n’est spécifiée pour un type de base, la cellule n’affiche aucune icône. Toutefois, si une valeur d’entité ne spécifie pas d’icône, elle affiche une icône par défaut dans la valeur de cellule.

Valeurs numériques formatées

Vous pouvez appliquer une mise en forme numérique à des valeurs de type CellValueType.double. Utilisez la numberFormat propriété dans le schéma JSON pour spécifier un format numérique. L’exemple de code suivant montre le schéma complet d’une valeur numérique mise en forme en tant que devise. La valeur numérique mise en forme dans l’exemple de code s’affiche sous la forme $24.00 dans l’interface utilisateur Excel.

// This is an example of the complete JSON of a formatted number value with a property.
// In this case, the number is formatted as currency.
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: "dollar"
                        }
                    }
                }
            ]
        ];
        await context.sync();
    });
}

La mise en forme des nombres est considérée comme le format par défaut. Si l’utilisateur, ou un autre code, applique une mise en forme à une cellule contenant un nombre mis en forme, le format appliqué remplace le format du nombre.

Disposition de carte

Les valeurs de cellule avec des propriétés ont un type de données par défaut carte que l’utilisateur peut afficher. Vous pouvez fournir une disposition de carte personnalisée à utiliser au lieu de la disposition de carte par défaut pour améliorer l’expérience utilisateur lors de l’affichage des propriétés. Pour ce faire, ajoutez la propriété layouts à la description JSON.

Pour plus d’informations, consultez Utiliser des cartes avec des types de données de valeur de cellule.

Types de données imbriqués

Vous pouvez imbriquer des types de données dans une valeur de cellule, telles que des valeurs d’entité supplémentaires, ainsi que des chaînes, des doubles et des booléens. L’exemple de code suivant montre comment créer une valeur de cellule qui représente la charge status sur une batterie d’ordinateur. Il contient une valeur d’entité imbriquée qui décrit les propriétés de l’ordinateur pour la consommation d’énergie et la charge status. La valeur de l’entité ordinateur contient également une valeur de chaîne imbriquée qui décrit le plan d’alimentation de l’ordinateur.

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 numérique 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é des types de données, les utilisateurs voient un avertissement de Type de données non disponible. La valeur s’affiche toujours dans la cellule et les fonctions comme prévu avec des formules et d’autres fonctionnalités Excel. Si la valeur est un nombre mis en forme, les calculs utilisent à la basicValue place du nombre mis en forme.

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

Voir aussi

• Excel Concepts fondamentaux des types de données de l’API JavaScript