Partager via

Utiliser des cartes avec des types de données de valeur de cellule

Vous pouvez spécifier carte fenêtres modales dans l’interface utilisateur Excel pour différents types de données de valeur de cellule. Les cartes peuvent afficher des informations supplémentaires au-delà de ce qui est déjà visible dans une cellule, telles que les images associées, les informations sur les catégories de produits 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 pour les valeurs de cellule.

Les cartes sont prises en charge pour les types de valeurs de cellule suivants.

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.

Type de données valeur d’entité avec la fenêtre carte affichée.

Propriétés de la carte

Utilisez properties pour spécifier toutes les informations personnalisées sur vos types de données. La properties clé prend en charge 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.double,
            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.

Type de données valeur d’entité avec la fenêtre de disposition carte affichée. Le carte affiche le nom du produit, l’ID de produit, la quantité par unité et les informations sur le prix unitaire.

Disposition de carte

Les valeurs de cellule ont un type de données par défaut carte que l’utilisateur peut afficher. Spécifiez une disposition de carte personnalisée pour améliorer l’expérience utilisateur lors de l’affichage des propriétés. La layouts propriété définit la structure et l’apparence du carte. Permet layouts de spécifier des attributs tels qu’une icône, un titre carte, une 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 le carte est ouvert. La compact propriété est facultative et définit l’icône d’une valeur. L’icône s’affiche dans la valeur de cellule si elle est fournie. Il peut également être affiché dans le carte s’il est référencé en tant que sous-propriété.

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.

Conseil

La layout clé a également des options d’affichage supplémentaires disponibles au-delà "List" de carte sections. Utilisez "Table" pour Excel.CardLayoutTableSection et "TwoColumn" pour Excel.CardLayoutTwoColumnSection. Notez que la "TwoColumn" disposition est disponible uniquement en préversion.

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.

Type de données valeur d’entité avec la fenêtre de disposition carte affichée. Le carte affiche le titre et les sections du carte.

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 .

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.double,
        basicValue: product.unitPrice,
        numberFormat: "$* #,##0.00",
        propertyMetadata: {
          sublabel: "USD"
        }
    },

Attribution

Ajoutez l’attribution des informations provenant de tiers pour indiquer la source et les informations de licence. Utilisez Excel.CellValueAttributionAttributes pour ajouter l’attribution à une valeur de cellule. L’exemple de code suivant montre comment ajouter une attribution pour l’utilisation d’informations sur la planète Mars à partir de Wikipédia.

async function createPlanet() {
    await Excel.run(async (context) => {
        const sheet = context.workbook.worksheets.getActiveWorksheet();
        const range = sheet.getRange("A1");
        const attributionObject: Excel.CellValueAttributionAttributes = {
            licenseAddress: "https://en.wikipedia.org/wiki/Wikipedia:Wikipedia_is_free_content",
            licenseText: "Free usage information",
            sourceAddress: "https://en.wikipedia.org/wiki/Mars",
            sourceText: "Wikipedia"
        };

        range.valuesAsJson = [
            [
                {
                    type: Excel.CellValueType.double,
                    basicType: Excel.RangeValueType.double,
                    basicValue: 6779, // kilometers (radius)
                    properties: {
                        Name: {
                            type: Excel.CellValueType.string,
                            basicType: Excel.RangeValueType.string,
                            basicValue: "Mars",
                            propertyMetadata: {
                                sublabel: "Planetary Body",
                                attribution: [attributionObject]
                            }
                        }
                    }
                }
            ]
        ];
        await context.sync();
    });
}

L’image suivante montre comment l’attribution est affichée dans le type de données carte pour l’utilisateur.

Type de données carte montrant l’attribution pour Wikipédia.

Informations sur le fournisseur

Vous pouvez ajouter des informations sur votre complément ou service, qui sont la source des informations dans le type de données carte. Utilisez Excel.CellValueProviderAttributes pour ajouter les informations de votre fournisseur. L’exemple de code suivant montre comment ajouter des informations de fournisseur pour la recherche générique Contoso comme source de données de recherche pour la valeur de cellule.

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

        range.valuesAsJson = [
            [
                {
                    type: Excel.CellValueType.string,
                    basicType: Excel.RangeValueType.string,
                    basicValue: "cell function - Microsoft support",
                    properties: {
                        "Search Keywords": {
                            type: Excel.CellValueType.string,
                            basicType: Excel.RangeValueType.string,
                            basicValue: "Cell Values"
                        }
                    },
                    provider: {
                        description: "Contoso generic search",
                        // Image credit: Ignacio javier igjav, Public domain, via Wikimedia Commons
                        logoSourceAddress: "https://upload.wikimedia.org/wikipedia/commons/f/f9/Lupa.png",
                        logoTargetAddress: "https://contoso.com"
                    }
                }
            ]
        ];

        await context.sync();
    });
}

L’image suivante montre comment les informations du fournisseur apparaissent en tant que logo dans le type de données carte pour l’utilisateur.

Type de données carte affichant le logo de recherche pour la recherche générique Contoso.

Étapes suivantes

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.

Voir aussi

  • Last updated on