Utiliser des types de données dans les compléments Excel

Lorsque votre complément a besoin de plus de chaînes, de nombres et de booléens, utilisez des types de données Excel. Les types de données vous permettent de retourner des valeurs améliorées telles que des dates mises en forme, des cartes d’entité, des enregistrements liés et des images web tout en prenant en charge les calculs de feuille de calcul.

Cet article explique l’API qui alimente les valuesAsJson types de données et indique quand utiliser les types de valeurs de cellule principales. Pour obtenir une vue d’ensemble des fonctionnalités, consultez Vue d’ensemble des types de données dans les compléments Excel.

Pour essayer ces concepts immédiatement, ouvrez Script Lab dans Excel et parcourez les exemples de types de données dans la bibliothèque Exemples.

la propriété valuesAsJson

La valuesAsJson propriété est l’API principale pour la lecture et l’écriture de types de données Excel. La propriété au singulier valueAsJson sur NamedItem a le même objectif pour un seul élément nommé.

valuesAsJson développe des propriétés telles que Range.values. La values propriété retourne uniquement l’un des quatre types de valeurs de cellule de base : chaîne, nombre, booléen ou erreur. En revanche, valuesAsJson retourne une structure JSON développée pour ces types de base et pour les types de données tels que les nombres mis en forme, les entités et les images web.

Les objets suivants exposent valuesAsJson.

Remarque

Certaines valeurs de cellule changent en fonction des paramètres régionaux d’un utilisateur. Utilisez valuesAsJsonLocal quand vous avez besoin de valeurs localisées. Il est disponible sur les mêmes objets que valuesAsJson.

Valeurs de cellule

valuesAsJson retourne l’alias de type CellValue . CellValue est une union de plusieurs types de valeurs de cellule.

Les types utilisés par la plupart des compléments sont les suivants :

L’union complète CellValue inclut les types suivants.

CellValue est une intersection avec CellValueExtraProperties. CellValueExtraProperties n’est pas un type de données en soi. Il ajoute des propriétés qui vous aident à contrôler la façon dont les valeurs de cellule sont remplacées.

Schéma JSON

Chaque valeur retournée valuesAsJson utilise un schéma de métadonnées JSON conçu pour ce type de valeur de cellule. Bien que chaque type ait ses propres propriétés, tous les schémas partagent type, basicTypeet basicValue.

type définit le CellValueType. basicType est en lecture seule et fournit le type de secours lorsque le type de données n’est pas pris en charge ou est mis en forme de manière incorrecte. basicValue correspond à la valeur retournée par la values propriété et sert de secours lorsque les calculs rencontrent des scénarios incompatibles, comme une version antérieure d’Excel qui ne prend pas en charge les types de données. basicValue est en lecture seule pour ArrayCellValue, EntityCellValue, LinkedEntityCellValueet WebImageCellValue.

Au-delà de ces champs partagés, chaque *CellValue type a son propre schéma. Par exemple, WebImageCellValue inclut altText et attribution, tandis qu’EntityCellValue inclut properties et text.

Les sections suivantes présentent des modèles courants pour les nombres mis en forme, les valeurs de base avec des propriétés supplémentaires, des valeurs d’entité, des entités liées, des images web et des erreurs améliorées.

Valeurs numériques formatées

Utilisez DoubleCellValue lorsque la valeur numérique sous-jacente est importante, mais vous souhaitez également qu’Excel conserve un format d’affichage spécifique avec cette valeur. Un scénario courant consiste à retourner une valeur de date de série et à l’afficher sous forme de date dans la feuille de calcul.

L’exemple suivant montre le schéma JSON complet pour un nombre mis en forme. Dans cet exemple, myDate s’affiche sous la forme 16/1/1990 dans l’interface utilisateur Excel. Si les exigences de compatibilité minimale pour les types de données ne sont pas remplies, les calculs utilisent basicValue.

const myDate: Excel.DoubleCellValue = {
    type: Excel.CellValueType.double,
    basicValue: 32889.0,
    basicType: Excel.RangeValueType.double, // A read-only property. Used as a fallback in incompatible scenarios.
    numberFormat: "m/d/yyyy"
};

Le format numérique dans un DoubleCellValue est le format par défaut. Si un utilisateur ou une autre partie de votre complément applique ultérieurement la mise en forme à la cellule, ce format appliqué remplace le format de la valeur.

Pour tester des valeurs numériques mises en forme, ouvrez Script Lab et exécutez l’exemple Types de données : Nombres mis en forme.

Valeurs de base des cellules

Vous pouvez ajouter des propriétés à des valeurs Excel de base pour y associer des informations supplémentaires. Ce modèle fonctionne avec les types de base chaîne, double et booléen . Utilisez-la quand vous souhaitez qu’une valeur de cellule simple transporte des champs associés sans transformer la valeur en entité complète.

Par exemple, un total de factures peut inclure des champs connexes tels que Boissons, Nourriture, Taxe et Pourboire.

Capture d’écran des champs boissons, nourriture, taxe et pourboire affichés pour la valeur de cellule sélectionnée.

Pour obtenir la procédure pas à pas complète, consultez Ajouter des propriétés à des valeurs de cellule de base Excel.

Valeurs d’entité

Une EntityCellValue peut stocker du texte, des types de données imbriqués et des tableaux, et Excel peut afficher ces données dans une entité carte.

L’exemple suivant montre le schéma JSON complet pour une valeur d’entité qui représente une facture. L’entité inclut le texte d’affichage, ainsi que les propriétés d’une image, une date d’échéance et une valeur de status.

const myEntity: Excel.EntityCellValue = {
    type: Excel.CellValueType.entity,
    text: "A llama",
    properties: {
        image: myImage,
        "start date": myDate,
        "quote": {
            type: Excel.CellValueType.string,
            basicValue: "I love llamas."
        }
    }, 
    basicType: Excel.RangeValueType.error, // A read-only property. Used as a fallback in incompatible scenarios.
    basicValue: "#VALUE!" // A read-only property. Used as a fallback in incompatible scenarios.
};

Les basicType propriétés et basicValue définissent la façon dont les calculs lisent une entité lorsque les exigences de compatibilité minimale pour les types de données ne sont pas remplies. Dans ce cas, l’entité s’affiche sous la forme d’une erreur #VALUE ! dans l’interface utilisateur Excel.

Importante

Une valeur d’entité peut définir un referencedValues tableau qui stocke des valeurs de cellule supplémentaires. Ces valeurs sont référencées par l’index à partir de l’élément de propertiesl’entité .

  • Le referencedValues tableau est pris en charge uniquement sur l’entité de niveau racine dans une arborescence de valeurs de cellule.
  • Les entités imbriquées, qui sont des entités utilisées comme valeurs de propriété à l’intérieur d’une autre entité, ne doivent pas définir leur propre referencedValues.
  • Si une entité imbriquée inclut un referencedValues tableau, l’API Excel JavaScript génère une GeneralException erreur dans le code de complément ou de script, ou Excel affiche une erreur #VALUE ! lorsqu’une fonction personnalisée génère la valeur.

Pour référencer des valeurs d’une entité imbriquée, utilisez des index ReferenceCellValue qui pointent vers le tableau de l’entité referencedValues racine.

Pour explorer les types de données d’entité, ouvrez Script Lab et exécutez Types de données : créer des cartes d’entité à partir de données d’une table. Pour obtenir des exemples plus approfondis, consultez Types de données : valeurs d’entité avec références et Types de données : propriétés d’attribution de valeur d’entité.

Valeurs des cellules d’entité liée

LinkedEntityCellValue représente une entité connectée à une source de données externe. Utilisez des entités liées lorsque vous avez besoin de cartes pour des jeux de données volumineux ou fréquemment mis à jour et que vous ne souhaitez pas charger tous les détails dans le classeur à la fois.

Les domaines de données Stocks et Geography disponibles dans l’interface utilisateur Excel sont des exemples de valeurs de cellule d’entité liée.

Les valeurs de cellule d’entité liée offrent les avantages suivants par rapport aux valeurs d’entité normales.

  • Les valeurs de cellule d’entité liée peuvent s’imbriquer, et Excel ne récupère pas les entités liées imbriquées tant que l’utilisateur ou la feuille de calcul ne les référence pas. Ce comportement permet de réduire la taille du fichier et d’améliorer les performances des classeurs.
  • Excel utilise un cache afin que différentes cellules puissent référencer la même valeur de cellule d’entité liée. Cela contribue également aux performances des classeurs.

Pour plus d’informations sur l’implémentation, consultez Créer des types de données d’entité liée dans des compléments Excel.

Valeurs d’image Web

Utilisez WebImageCellValue lorsque votre complément doit stocker une image dans une plage ou dans le cadre d’une valeur d’entité. Ce type inclut des propriétés telles que address, altTextet relatedImagesAddress.

Les basicType propriétés et basicValue définissent la façon dont les calculs lisent une image web lorsque les exigences de compatibilité minimale pour les types de données ne sont pas remplies. Dans ce cas, l’image web s’affiche sous la forme d’une erreur #VALUE ! dans l’interface utilisateur Excel.

L’exemple suivant montre le schéma JSON complet d’une image web.

const myImage: Excel.WebImageCellValue = {
    type: Excel.CellValueType.webImage,
    address: "https://bit.ly/2YGOwtw",
    basicType: Excel.RangeValueType.error,
    basicValue: "#VALUE!"
};

Pour essayer les types de données d’image web, ouvrez Script Lab et exécutez Types de données : Images web.

Amélioration de la prise en charge des erreurs

Les API de types de données exposent les erreurs existantes de l’interface utilisateur Excel en tant qu’objets. Cette approche permet à votre complément de définir ou de récupérer des propriétés telles que type, errorTypeet errorSubType.

Les objets d’erreur suivants ont développé la prise en charge via des types de données.

Chaque objet d’erreur peut accéder à un enum via errorSubType. Cette énumération fournit plus de détails sur l’erreur spécifique. Par exemple, BlockedErrorCellValueSubType fournit des informations supplémentaires sur la raison pour laquelle un BlockedErrorCellValue s’est produit.

Pour en savoir plus, ouvrez Script Lab et exécutez Types de données : Définir des valeurs d’erreur.

Étapes suivantes

Voir aussi

  • Last updated on