Utiliser des cartes avec des types de données de valeur d’entité
Cet article explique comment utiliser l’API JavaScript Excel pour créer carte fenêtres modales dans l’interface utilisateur Excel avec des types de données valeur d’entité. Ces cartes peuvent afficher des informations supplémentaires contenues dans une valeur d’entité, au-delà de ce qui est déjà visible dans une cellule, comme les images associées, les informations de catégorie de produit et les attributions de données.
Remarque
Cet article développe les informations décrites dans l’article Concepts de base des types de données Excel . Nous vous recommandons de lire cet article avant d’en savoir plus sur les cartes d’entité.
Une valeur d’entité, ou EntityCellValue, est un conteneur pour les types de données et similaire à un objet dans la programmation orientée objet. Cet article explique comment utiliser la valeur d’entité carte propriétés, les options de disposition et la fonctionnalité d’attribution de données pour créer des valeurs d’entité qui s’affichent sous forme de cartes.
La capture d’écran suivante montre un exemple de valeur d’entité ouverte carte, dans ce cas pour le produit Chef Anton’s Gumbo Mix à partir d’une liste de produits d’épicerie.
Propriétés de la carte
La propriété de valeur properties d’entité vous permet de définir des informations personnalisées sur vos types de données. La properties clé accepte les types de données imbriqués. Chaque propriété imbriquée, ou type de données, doit avoir un type paramètre et basicValue .
Importante
Les types de données imbriqués properties sont utilisés en combinaison avec les valeurs de disposition de carte décrites dans la section d’article suivante. Après avoir défini un type de données imbriqué dans properties, il doit être affecté dans la layouts propriété à afficher sur le carte.
L’extrait de code suivant montre le JSON d’une valeur d’entité avec plusieurs types de données imbriqués dans properties.
Remarque
Pour tester cet extrait de code dans un exemple complet, ouvrez Script Lab dans Excel et sélectionnez Types de données : créer des cartes d’entité à partir de données d’un tableau dans notre bibliothèque d’exemples.
const entity: Excel.EntityCellValue = {
type: Excel.CellValueType.entity,
text: productName,
properties: {
"Product ID": {
type: Excel.CellValueType.string,
basicValue: productID.toString() || ""
},
"Product Name": {
type: Excel.CellValueType.string,
basicValue: productName || ""
},
"Image": {
type: Excel.CellValueType.webImage,
address: product.productImage || ""
},
"Quantity Per Unit": {
type: Excel.CellValueType.string,
basicValue: product.quantityPerUnit || ""
},
"Unit Price": {
type: Excel.CellValueType.formattedNumber,
basicValue: product.unitPrice,
numberFormat: "$* #,##0.00"
},
Discontinued: {
type: Excel.CellValueType.boolean,
basicValue: product.discontinued || false
}
},
layouts: {
// Enter layout settings here.
}
};
La capture d’écran suivante montre une valeur d’entité carte qui utilise l’extrait de code précédent. La capture d’écran montre l’ID de produit, le nom du produit, l’image, la quantité par unité et le prix unitaire de l’extrait de code précédent.
Métadonnées de propriété
Les propriétés d’entité ont un champ facultatif propertyMetadata qui utilise l’objet CellValuePropertyMetadata et offre les propriétés attribution, excludeFromet sublabel. L’extrait de code suivant montre comment ajouter un sublabel à la "Unit Price" propriété à partir de l’extrait de code précédent. Dans ce cas, la sous-étiquette identifie le type de devise.
Remarque
Le propertyMetadata champ n’est disponible que sur les types de données imbriqués dans les propriétés d’entité.
// This code snippet is an excerpt from the `properties` field of the
// preceding `EntityCellValue` snippet. "Unit Price" is a property of
// an entity value.
"Unit Price": {
type: Excel.CellValueType.formattedNumber,
basicValue: product.unitPrice,
numberFormat: "$* #,##0.00",
propertyMetadata: {
sublabel: "USD"
}
},
La capture d’écran suivante montre une valeur d’entité carte qui utilise l’extrait de code précédent, affichant les métadonnées sublabel de propriété usd en regard de la propriété Unit Price.
Disposition de carte
La propriété de valeur layouts d’entité définit l’apparence de l’entité. Utilisez layouts pour spécifier des attributs tels qu’une icône d’entité, carte titre, l’image d’un carte et le nombre de sections à afficher.
Importante
Les valeurs imbriquées layouts sont utilisées en combinaison avec les types de données des propriétés de carte décrits dans la section précédente de l’article. Un type de données imbriqué doit être défini dans properties avant de pouvoir être affecté dans layouts pour s’afficher sur le carte.
La layouts propriété contient deux sous-propriétés directes, compact et card. La card propriété spécifie l’apparence d’un carte lorsque l’entité carte est ouverte. La compact propriété définit uniquement l’icône d’une entité, et cette icône s’affiche uniquement lorsque l’carte est dans son état compact ou non ouvert. Consultez l’énumération EntityCompactLayoutIcons pour obtenir la liste complète des icônes disponibles. L’extrait de code suivant montre comment afficher l’icône shoppingBag .
Dans la card propriété , utilisez l’objet CardLayoutStandardProperties pour définir les composants du carte comme title, subTitleet sections.
La valeur d’entité JSON dans l’extrait de code suivant montre une card disposition avec des objets et mainImage imbriquéstitle, ainsi que trois sections dans le carte. Notez que la title propriété "Product Name" a un type de données correspondant dans la section précédente de l’article Propriétés de carte . La mainImage propriété a également un type de données correspondant "Image" dans la section précédente. La sections propriété prend un tableau imbriqué et utilise l’objet CardLayoutSectionStandardProperties pour définir l’apparence de chaque section.
Dans chaque section carte, vous pouvez spécifier des éléments tels que layout, titleet properties. La layout clé utilise l’objet CardLayoutListSection et accepte la valeur "List". La properties clé accepte un tableau de chaînes. Notez que les properties valeurs, telles que "Product ID", ont des types de données correspondants dans la section précédente de l’article Propriétés de carte . Les sections peuvent également être réductibles et peuvent être définies avec des valeurs booléennes comme réduites ou non réduites lorsque l’entité carte est ouverte dans l’interface utilisateur Excel.
Remarque
Pour tester cet extrait de code dans un exemple complet, ouvrez Script Lab dans Excel et sélectionnez Types de données : créer des cartes d’entité à partir de données d’un tableau dans notre bibliothèque d’exemples.
const entity: Excel.EntityCellValue = {
type: Excel.CellValueType.entity,
text: productName,
properties: {
// Enter property settings here.
},
layouts: {
compact: {
icon: Excel.EntityCompactLayoutIcons.shoppingBag
},
card: {
title: {
property: "Product Name"
},
mainImage: {
property: "Image"
},
sections: [
{
layout: "List",
properties: ["Product ID"]
},
{
layout: "List",
title: "Quantity and price",
collapsible: true,
collapsed: false, // This section will not be collapsed when the card is opened.
properties: ["Quantity Per Unit", "Unit Price"]
},
{
layout: "List",
title: "Additional information",
collapsible: true,
collapsed: true, // This section will be collapsed when the card is opened.
properties: ["Discontinued"]
}
]
}
}
};
La capture d’écran suivante montre une valeur d’entité carte qui utilise les extraits de code précédents. Dans la capture d’écran, l’icône shoppingBag s’affiche à côté des noms de produits dans la feuille de calcul. Dans l’entité carte, l’objet mainImage s’affiche en haut, suivi de l’objet title qui utilise le nom du produit et est défini sur Gumbo Mix de Chef Anton. La capture d’écran montre sectionségalement . La section Quantité et prix est réductible et contient Quantité par unité et Prix unitaire. Le champ Informations supplémentaires est réductible et réduit lorsque le carte est ouvert.
Remarque
Dans la capture d’écran précédente, l’icône branch s’affiche à côté des condiments dans la section Catégorie . Consultez l’exemple Types de données : créer des cartes d’entité à partir de données dans un tableau pour savoir comment définir des icônes imbriquées comme l’icône de section Catégorie .
Il existe un problème connu avec les icônes imbriquées dans Excel sur Mac. Dans cet environnement, les icônes imbriquées s’affichent toujours en tant qu’icône, quelle que generic soit l’icône sélectionnée avec l’énumération EntityCompactLayoutIcons .
Attribution des données de carte
Les cartes de valeur d’entité peuvent afficher une attribution de données pour accorder du crédit au fournisseur des informations dans l’entité carte. La propriété de valeur provider d’entité utilise l’objet CellValueProviderAttributes , qui définit les descriptionvaleurs , logoSourceAddresset logoTargetAddress .
La propriété du fournisseur de données affiche une image dans le coin inférieur gauche de l’entité carte. Il utilise pour logoSourceAddress spécifier une URL source pour l’image. La logoTargetAddress valeur définit la destination de l’URL si l’image du logo est sélectionnée. La description valeur s’affiche sous la forme d’une info-bulle lorsque vous pointez sur le logo. La description valeur s’affiche également sous forme de secours en texte brut si n’est logoSourceAddress pas défini ou si l’adresse source de l’image est rompue.
Le code JSON dans l’extrait de code suivant montre une valeur d’entité qui utilise la provider propriété pour spécifier une attribution de fournisseur de données pour l’entité.
Remarque
Pour tester cet extrait de code dans un exemple complet, ouvrez Script Lab dans Excel et sélectionnez Types de données : propriétés d’attribution de valeur d’entité dans notre bibliothèque d’exemples.
const entity: Excel.EntityCellValue = {
type: Excel.CellValueType.entity,
text: productName,
properties: {
// Enter property settings here.
},
layouts: {
// Enter layout settings here.
},
provider: {
description: product.providerName, // Name of the data provider. Displays as a tooltip when hovering over the logo. Also displays as a fallback if the source address for the image is broken.
logoSourceAddress: product.sourceAddress, // Source URL of the logo to display.
logoTargetAddress: product.targetAddress // Destination URL that the logo navigates to when selected.
}
};
La capture d’écran suivante montre une valeur d’entité carte qui utilise l’extrait de code précédent. La capture d’écran montre l’attribution du fournisseur de données dans le coin inférieur gauche. Dans cette instance, le fournisseur de données est Microsoft et le logo Microsoft s’affiche.
Prochaines étapes
Essayez l’exemple Créer et explorer des types de données dans Excel dans notre référentiel OfficeDev/Office-Add-in-samples . Cet exemple vous guide tout au long de la génération, puis du chargement indépendant d’un complément qui crée et modifie des types de données dans un classeur.