Partager via

Concepts de base des types de données Excel

  • Article

Cet article explique comment utiliser l’API JavaScript Excel pour utiliser des types de données. Il présente des concepts fondamentaux pour le développement de types de données.

la propriété valuesAsJson

La valuesAsJson propriété (ou le singulier valueAsJson pour NamedItem) fait partie intégrante de la création de types de données dans Excel. Cette propriété est une extension des propriétés values, telles que Range.values. Les propriétésvalues et valuesAsJson sont utilisées pour accéder à la valeur dans une cellule, mais la propriété values retourne uniquement l’un des quatre types de base : chaîne, nombre, booléen ou erreur (sous forme de chaîne). En revanche, valuesAsJson retourne des informations développées sur les quatre types de base, et cette propriété peut retourner des types de données tels que des valeurs numériques mises en forme, des entités et des images web.

Les objets suivants proposent la propriété valuesAsJson.

Notes

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.

Valeurs de cellule

La valuesAsJson propriété renvoie un alias de type CellValue, qui est une union des types de données suivants.

L’alias de type CellValue retourne également l’objet CellValueExtraProperties, qui est une intersection avec le reste des types *CellValue. Il ne s’agit pas d’un type de données lui-même. Les propriétés de l’objet CellValueExtraProperties sont utilisées avec tous les types de données pour spécifier des détails liés au remplacement des valeurs de cellule.

Schéma JSON

Chaque type de valeur de cellule retourné par valuesAsJson utilise un schéma de métadonnées JSON conçu pour ce type. Outre les propriétés supplémentaires propres à chaque type de données, ces schémas de métadonnées JSON ont tous les propriétés type, basicTypeet basicValue en commun.

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

Outre les trois champs que tous les types de données partagent, le schéma de métadonnées JSON pour chaque *CellValue a des propriétés disponibles en fonction de ce type. Par exemple, le type WebImageCellValue inclut les propriétés altText et attribution , tandis que le type EntityCellValue offre les champs properties et text.

Les sections suivantes montrent des exemples de code JSON pour la valeur numérique mise en forme, la valeur d’entité et les types de données d’image web.

Valeurs numériques formatées

L’objet FormattedNumberCellValue permet aux Excel de définir une propriété numberFormat pour une valeur. Une fois affecté, ce format de nombre parcourt les calculs avec la valeur et peut être renvoyé par des fonctions.

L’exemple de code JSON suivant montre le schéma complet d’une valeur numérique mise en forme. La valeur numérique mise en formemyDate dans l’exemple de code s’affiche comme 16/16/1990 dans l Excel’interface utilisateur. Si les exigences de compatibilité minimales pour la fonctionnalité de types de données ne sont pas remplies, les calculs utilisent le basicValue à la place nombre mis en forme.

// This is an example of the complete JSON of a formatted number value.
// In this case, the number is formatted as a date.
const myDate: Excel.FormattedNumberCellValue = {
    type: Excel.CellValueType.formattedNumber,
    basicValue: 32889.0,
    basicType: Excel.RangeValueType.double, // A read-only property. Used as a fallback in incompatible scenarios.
    numberFormat: "m/d/yyyy"
};

Commencez à expérimenter des valeurs numériques mises en forme en ouvrant Script Lab et en consultant l’extrait de code Types de données : Nombres mis en forme dans notre bibliothèque d’exemples .

Valeurs d’entité

Une valeur d’entité est un conteneur pour les types de données, semblable à un objet dans la programmation orientée objet. Les entités sont également des tableaux en tant que propriétés d’une valeur d’entité. L’objet EntityCellValue permet aux compléments de définir des propriétés telles type que , et textproperties . La properties propriété permet à la valeur d’entité de définir et de contenir des types de données supplémentaires.

Les propriétés basicType et basicValuedéfinissent la manière dont les calculs lisent ce type de données d’entité si les exigences de compatibilité minimales pour utiliser les types de données ne sont pas remplies. Dans ce scénario, ce type de données d’entité s’affiche sous la forme d’une erreur #VALUE ! dans l’interface utilisateur Excel.

L’exemple de code JSON suivant montre le schéma complet d’une valeur d’entité qui contient du texte, une image, une date et une valeur de texte supplémentaire.

// This is an example of the complete JSON for an entity value.
// The entity contains text and properties which contain an image, a date, and another text value.
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 valeurs d’entité offrent également une propriété layouts qui crée une carte pour l’entité. La carte s’affiche sous forme de fenêtre modale dans l’interface utilisateur Excel et peut afficher des informations supplémentaires contenues dans la valeur de l’entité, au-delà de ce qui est visible dans la cellule. Pour plus d’informations, consultez Utiliser des cartes avec des types de données de valeur d’entité.

Pour explorer les types de données d’entité, commencez par aller à Script Lab dans Excel et ouvrez types de données : créer des cartes d’entité à partir de données dans un extrait de tableau dans notre bibliothèque d’exemples . Les extraits de code des propriétés d’attribution De données : Valeurs d’entité avec références et Types de données : Propriétés d’attribution de valeur d’entité offrent un examen plus approfondi des fonctionnalités d’entité.

Entités liées

Les valeurs d’entité liées, ou objets LinkedEntityCellValue sont un type de valeur d’entité. Ces objets intègrent les données fournies par un service externe et peuvent afficher ces données sous la forme d’une carte d’entité, comme des valeurs d’entité régulières. Les types de données Actions et Géographie disponibles via l’interface utilisateur Excel sont des valeurs d’entité liées.

Valeurs d’image Web

L’objet WebImageCellValue crée la possibilité de stocker une image dans le cadre d’une entité ou en tant que valeur indépendante dans une plage. Cet objet offre de nombreuses propriétés, notamment addressaltText , et relatedImagesAddress .

Les propriétés basicType et basicValue définissent la manière dont les calculs lisent le type de données d’image web si les exigences de compatibilité minimales requises pour utiliser la fonctionnalité des types de données ne sont pas remplies. Dans ce scénario, ce type de données d’image web s’affiche sous la forme d’une erreur #VALUE ! dans l’interface utilisateur Excel.

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

// This is an example of the complete JSON for a web image.
const myImage: Excel.WebImageCellValue = {
    type: Excel.CellValueType.webImage,
    address: "https://bit.ly/2YGOwtw", 
    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.
};

Essayez les types de données d’image web en ouvrant Script Lab et en sélectionnant l’extrait de code Types de données : Images web dans notre bibliothèque d’exemples .

Amélioration de la prise en charge des erreurs

Les API de types de données exposent les erreurs existantes de l'interface utilisateur d'Excel sous forme d'objets. Maintenant que ces erreurs sont accessibles en tant qu’objets, les compléments peuvent définir ou récupérer des propriétés telles type, errorType et errorSubType .

Voici une liste de tous les objets d’erreur avec prise en charge étendue via les types de données.

Chacun des objets d’erreur peut accéder à une enum via la propriété, et cette enum contient des données supplémentaires errorSubType sur l’erreur. Par exemple, BlockedErrorCellValue l’objet d’erreur peut accéder à l’enum BlockedErrorCellValueSubType. BlockedErrorCellValueSubTypeL’enum fournit des données supplémentaires sur la cause de l’erreur.

Pour en savoir plus sur les objets d’erreur des types de données, consultez l’extrait de code Types de données : Définir des valeurs d’erreur dans notre bibliothèque d’exemplesde labo de script.

Étapes suivantes

Découvrez comment les types de données d’entité étendent le potentiel des compléments Excel au-delà d’une grille à 2 dimensions avec l’article Utiliser des cartes avec des types de données valeur d’entité .

Utilisez l’exemple Créer et explorer des types de données dans Excel dans notre référentiel OfficeDev/Office-Add-in-samples pour expérimenter plus en profondeur les types de données en créant et en chargeant une version test d’un complément qui crée et modifie des types de données dans un classeur.

Voir aussi