Créer des types de données d’entité liée dans des compléments Excel

Utilisez des valeurs de cellule d’entité liée lorsque votre complément Excel doit afficher des données externes sans stocker le jeu de données complet dans le classeur. Par exemple, vous pouvez afficher un produit, un client ou un fournisseur dans une cellule, ouvrir une carte enrichie pour plus de détails et charger des données imbriquées uniquement lorsqu’Excel en a besoin.

Excel utilise le même modèle pour les types de données liés intégrés tels que Stocks et Geography. Cet article explique comment créer votre propre fournisseur de données dans un complément Excel.

Dans cet article, vous allez apprendre à :

• Inscrire des domaines de données d’entité liée.
• Insérer des valeurs de cellule d’entité liée à partir d’une commande ou d’une fonction personnalisée.
• Implémentez une fonction de service de chargement d’entité liée.
• Configurez l’actualisation et la gestion des erreurs.

Avant de commencer, consultez les articles connexes suivants :

• Vue d’ensemble des types de données dans Excel de données
• Utiliser des types de données dans les compléments Excel
• Utiliser des cartes avec des types de données de valeur de cellule
• Ajouter des propriétés aux valeurs de base des cellules Excel

Ce que font les valeurs de cellule d’entité liée

Les valeurs de cellule d’entité liée connectent les cellules du classeur à une source de données externe et affichent le résultat sous la forme d’une carte d’entité.

Comme les valeurs d’entité normales, vous pouvez référencer des valeurs de cellule d’entité liée dans des formules.

Par rapport aux valeurs d’entité normales, les valeurs de cellule d’entité liée offrent ces avantages.

• Les valeurs des cellules d’entité liée imbriquées ne sont pas récupérées tant que l’utilisateur ou la feuille de calcul ne les référencent pas. Cela permet de réduire la taille du fichier et d’améliorer les performances des classeurs.
• Excel met en cache les valeurs des cellules d’entité liée afin que plusieurs cellules puissent référencer efficacement la même valeur.

Termes clés

Utilisez les termes suivants tout au long de cet article.

• Domaine de données d’entité liée : un domaine de données d’entité liée décrit la catégorie globale à laquelle appartient une entité. Les employés, les organisations ou les voitures en sont des exemples.
• Valeur de cellule d’entité liée : une instance créée à partir d’un domaine de données. Un exemple est une valeur d’employé pour une personne nommée Joe. Il peut être affiché en tant que valeur d’entité carte.
• Fournisseur de données : le fournisseur de données est reconnu par Excel comme source de données pour un ou plusieurs domaines de données d’entité liée inscrits.
• Fonction de service de chargement d’entité liée : chaque domaine de données d’entité liée définit une fonction de service de chargement pour qu’elle agisse comme source de données pour ce domaine. La fonction de service de chargement d’entités liées gère les demandes d’Excel pour obtenir les valeurs des cellules d’entité liée pour le classeur. Vous l’implémentez en tant que fonction personnalisée TypeScript ou JavaScript.

Fonctionnement du flux d’entité liée

Ce diagramme montre ce qui se passe après le chargement et l’insertion d’une valeur de cellule d’entité liée dans une cellule.

1. Excel charge votre complément, et celui-ci inscrit tous les domaines de données d’entité liée qu’il prend en charge. Chaque inscription inclut l’ID d’une fonction de service de chargement d’entité liée. Excel appelle cet ID ultérieurement pour demander des valeurs de propriété pour la valeur de cellule d’entité liée à partir du domaine de données d’entité liée. Dans cet exemple, un domaine de données nommé Products est inscrit.
2. Excel effectue le suivi de chaque domaine de données d’entité liée inscrit dans une collection de domaines de données d’entité liée. Cela permet à Excel d’appeler votre fonction de service de chargement d’entité liée lorsque des données sont nécessaires pour une valeur de cellule d’entité liée.
3. Votre complément insère une nouvelle valeur de cellule d’entité liée dans la feuille de calcul. Dans cet exemple, vous créez une nouvelle valeur de cellule d’entité liée pour le produit Chai. Cette étape se produit généralement lorsque l’utilisateur choisit un bouton sur votre complément qui entraîne la création d’une ou de plusieurs valeurs de cellule d’entité liée. Lorsque vous créez des valeurs de cellule d’entité liée, elles contiennent uniquement une chaîne de texte initiale qui s’affiche dans la cellule. Excel appelle votre fonction de service de chargement d’entité liée pour obtenir les valeurs de propriété restantes. Votre complément peut également créer des valeurs de cellule d’entité liée à partir de fonctions personnalisées.
4. Excel appelle la fonction de service de chargement d’entité liée que vous avez inscrite à l’étape 1. Cela se produit chaque fois que vous créez une valeur de cellule d’entité liée, ou si une actualisation des données se produit. Excel appelle votre fonction de service de chargement d’entité liée pour obtenir toutes les valeurs de propriété.
5. La fonction de service de chargement d’entité liée retourne une valeur de cellule d’entité liée à jour (Excel.LinkedEntityCellValue) pour l’ID d’entité liée (Excel.LinkedEntityId) demandé par Excel. En règle générale, votre fonction de service de chargement d’entité liée interroge une source de données externe pour obtenir les valeurs et créer la valeur de cellule d’entité liée. Dans cet exemple, les valeurs de l’ID de produit, de la catégorie, de la quantité et du prix sont retournées.

Les sections suivantes fournissent des détails supplémentaires sur les termes définis plus haut dans cet article.

Fournisseur de données

Votre complément est le fournisseur de données et est reconnu par Excel comme source de données pour un ou plusieurs domaines de données inscrits. Votre complément expose une ou plusieurs fonctions de fournisseur de données qui retournent des données pour les valeurs de cellule d’entité liée. Dans Excel.LinkedEntityDataDomainCreateOptions, définissez dataProvider sur une chaîne de texte telle que Contoso ou le nom de votre complément. Le nom doit être unique au sein de votre complément.

Domaines de données d’entité liée

Le fournisseur de données (votre complément) inscrit un ou plusieurs domaines de données. Un domaine de données décrit une entité dans Excel. Par exemple, un fournisseur de données peut fournir les domaines de données des produits et des catégories . Les domaines doivent être inscrits auprès d’Excel afin qu’il puisse travailler avec ces domaines pour récupérer et afficher les valeurs des cellules d’entité liée et effectuer des calculs.

Un domaine de données décrit à Excel les attributs suivants :

• Nom du fournisseur de données associé.
• ID de domaine permettant de l’identifier de manière unique, par exemple des produits.
• Nom d’affichage de l’utilisateur, tel que Products.
• Fonction de service de chargement d’entité liée à appeler quand Excel a besoin d’une valeur de cellule d’entité liée.
• Un mode d’actualisation et un intervalle spécifiés décrivant la fréquence d’actualisation.

Un exemple de domaine de données d’entité liée est le domaine de données Geography dans Excel qui fournit des valeurs de cellule d’entité liée pour les villes.

Valeur de cellule d’entité liée

Une valeur de cellule d’entité liée est une instance créée à partir d’un domaine de données. Un exemple est une valeur pour Seattle, à partir du domaine de données Geography. Il affiche une valeur d’entité carte comme des valeurs de cellule d’entité normales.

Étant donné que les valeurs de cellule d’entité liée sont liées au domaine de données, elles peuvent être actualisées. En outre, les valeurs des cellules d’entité liée imbriquées ne sont pas récupérées, sauf si l’utilisateur les demande (par exemple, l’affichage de l’entité carte). Et les valeurs des cellules d’entité imbriquées ne sont pas enregistrées avec la feuille de calcul, sauf si elles sont référencées à partir de la feuille de calcul (par exemple, une formule). Cela réduit la taille du fichier et améliore les performances.

Fonction de service de chargement d’entité liée

Chaque domaine de données nécessite une fonction qu’Excel peut appeler lorsqu’il a besoin de valeurs de cellule d’entité liée. Votre complément fournit le service sous la forme d’une fonction JavaScript ou TypeScript marquée avec @linkedEntityLoadService. Il est recommandé de créer une seule fonction de service de charge pour de meilleures performances. Excel envoie toutes les demandes de valeurs de cellule d’entité liée sous forme de lot à la fonction de service de chargement.

Créer un fournisseur de données avec des domaines de données

Les sections suivantes montrent comment écrire du code TypeScript pour un complément Excel qui fait office de fournisseur de données pour Contoso. Dans cet exemple, le complément fournit trois domaines de données : Produits, Catégories et Fournisseurs.

Inscrire les domaines de données

Commencez par inscrire chaque domaine de données pris en charge par votre complément. Dans cet exemple, le nom du fournisseur de données est Contoso et les domaines produits, catégories et fournisseurs.

Utilisez Excel.LinkedEntityDataDomainCreateOptions pour définir chaque domaine, y compris la fonction de service de chargement d’entité liée qu’Excel doit appeler. Ajoutez ensuite chaque domaine à la collection Workbook.linkedEntityDataDomains . Inscrivez des domaines lorsque vous initialisez votre complément Office.

Le code suivant inscrit les domaines de données Products, Categories et Suppliers .

Office.onReady(async () => {
    await Excel.run(async (context) => {
        const productsDomain: Excel.LinkedEntityDataDomainCreateOptions = {
            dataProvider: "Contoso",
            id: "products",
            name: "Products",
            // ID of the custom function that is called on demand by Excel to resolve or refresh linked entity cell values of this data domain.
            loadFunctionId: "CONTOSOLOADSERVICE",
            // periodicRefreshInterval is only required when supportedRefreshModes contains "Periodic".
            periodicRefreshInterval: 300,
            // Manual refresh mode is always supported, even if unspecified.
            supportedRefreshModes: [
                Excel.LinkedEntityDataDomainRefreshMode.periodic,
                Excel.LinkedEntityDataDomainRefreshMode.onLoad
            ]
        };

        const categoriesDomain: Excel.LinkedEntityDataDomainCreateOptions = {
            dataProvider: "Contoso",
            id: "categories",
            name: "Categories",
            loadFunctionId: "CONTOSOLOADSERVICE",
            periodicRefreshInterval: 300,
            supportedRefreshModes: [
                Excel.LinkedEntityDataDomainRefreshMode.periodic,
                Excel.LinkedEntityDataDomainRefreshMode.onLoad
            ]
        };

        const suppliersDomain: Excel.LinkedEntityDataDomainCreateOptions = {
            dataProvider: "Contoso",
            id: "suppliers",
            name: "Suppliers",
            loadFunctionId: "CONTOSOLOADSERVICE"
        };
        // Register the data domains by adding them to the collection.
        context.workbook.linkedEntityDataDomains.add(productsDomain);
        context.workbook.linkedEntityDataDomains.add(categoriesDomain);
        context.workbook.linkedEntityDataDomains.add(suppliersDomain);

        await context.sync();
    });
});

Insérer une valeur de cellule d’entité liée

Il existe deux façons d’insérer une valeur de cellule d’entité liée dans une cellule de feuille de calcul.

• Créez un bouton de commande dans le ruban ou un bouton dans le volet Office. Lorsque l’utilisateur sélectionne le bouton, votre code insère une valeur de cellule d’entité liée.
• Créez une fonction personnalisée qui retourne une valeur de cellule d’entité liée.

L’exemple suivant insère une nouvelle valeur de cellule d’entité liée dans la cellule sélectionnée. Vous pouvez appeler ce code à partir d’une commande du ruban ou d’un bouton dans le volet Office.

Gardez à l’esprit les exigences suivantes :

• Vous devez spécifier un serviceId de pour toutes les valeurs de 268436224 cellule d’entité liée que vous retournez. Cela informe Excel que la valeur de cellule d’entité liée est associée à un complément Excel.
• Vous devez spécifier un culture. Excel transmet cette valeur à votre fonction de service de chargement d’entité liée afin que vous puissiez conserver la culture d’origine lorsque le classeur est ouvert dans une autre culture.
• La text propriété est affichée à l’utilisateur dans la cellule pendant que la valeur des données d’entité liée est mise à jour. Cela empêche l’utilisateur de voir une cellule vide lorsque la mise à jour est terminée.

async function insertProduct() {
    await Excel.run(async (context) => {
        const productLinkedEntity: Excel.LinkedEntityCellValue = {
            type: Excel.CellValueType.linkedEntity,
            id: {
                entityId: "P1", // Don't use exclamation marks in this value.
                domainId: "products", // Don't use exclamation marks in this value.
                serviceId: 268436224,
                culture: "en-US",
            },
            text: "Chai",
        };
        context.workbook.getActiveCell().valuesAsJson = [[productLinkedEntity]];
        await context.sync();
    });
}

L’exemple de code suivant montre comment insérer une valeur de cellule d’entité liée à l’aide d’une fonction personnalisée. Un utilisateur peut obtenir une valeur de cellule d’entité liée en entrant =CONTOSO.GETPRODUCTBYID("productid") dans n’importe quelle cellule. Les notes de l’exemple de code précédent s’appliquent également à celui-ci.

/**
 * Custom function that shows how to insert a `LinkedEntityCellValue`.
 * @customfunction
 * @param {string} productID Unique ID of the product.
 * @return {any} `LinkedEntityCellValue` for the requested product, if found.
 */
function getProductById(productID: string): any {
    const product = getProduct(productID);
    if (product === null) {
        throw new CustomFunctions.Error(CustomFunctions.ErrorCode.notAvailable, "Invalid productID");
    }
    const productLinkedEntity: Excel.LinkedEntityCellValue = {
        type: Excel.CellValueType.linkedEntity,
        id: {
            entityId: product.productID,
            domainId: "products",
            serviceId: 268436224,
            culture: "en-US",
        },
        text: product.productName
    };

    return productLinkedEntity;
}

Implémenter la fonction de service de chargement d’entité liée

Le complément doit fournir une fonction de service de chargement d’entité liée pour gérer les demandes d’Excel lorsque des valeurs de propriété sont nécessaires pour toutes les valeurs de cellule d’entité liée. La fonction est identifiée par la @linkedEntityLoadService balise JSDoc.

L’exemple de code suivant montre comment créer une fonction qui gère les demandes de données à partir d’Excel pour les domaines de données Products et Categories . Remarques sur le code suivant :

• Il utilise des fonctions d’assistance pour créer les valeurs de cellule d’entité liée. Ce code est affiché ultérieurement.
• Si une erreur se produit, une erreur est générée CustomFunctions.ErrorCode.notAvailable . Cette erreur s’affiche #CONNECT! dans la cellule que l’utilisateur voit.

// Linked entity data domain constants
const productsDomainId = "products";
const categoriesDomainId = "categories";
const suppliersDomainId = "suppliers";

// Linked entity cell value constants
const addinDomainServiceId = 268436224;
const defaultCulture = "en-US";

/**
 * Custom function which acts as the "service" or the data provider for a `LinkedEntityDataDomain`, that is
 * called on demand by Excel to resolve/refresh `LinkedEntityCellValue`s of that `LinkedEntityDataDomain`.
 * @customfunction
 * @linkedEntityLoadService
 * @param {any} request Request to resolve/refresh `LinkedEntityCellValue` objects.
 * @return {any} Resolved/Refreshed `LinkedEntityCellValue` objects that were requested in the passed-in request.
 */
function contosoLoadService(request: any): any {
    const notAvailableError = new CustomFunctions.Error(CustomFunctions.ErrorCode.notAvailable);
    console.log(`Fetching linked entities from request: ${request} ...`);

    try {
        // Parse the request that was passed-in by Excel.
        const parsedRequest: Excel.LinkedEntityLoadServiceRequest = JSON.parse(request);
        // Initialize result to populate and return to Excel.
        const result: Excel.LinkedEntityLoadServiceResult = { entities: [] };

        // Identify the domainId of the request and call the corresponding function to create
        // linked entity cell values for that linked entity data domain.
        for (const { entityId } of parsedRequest.entities) {
            var linkedEntityResult = null;
            switch (parsedRequest.domainId) {
                case productsDomainId: {
                    linkedEntityResult = makeProductLinkedEntity(entityId);
                    break;
                }
                case categoriesDomainId: {
                    linkedEntityResult = makeCategoryLinkedEntity(entityId);
                    break;
                }
                case suppliersDomainId: {
                    linkedEntityResult = makeSupplierLinkedEntity(entityId);
                    break;
                }
                default:
                    throw notAvailableError;
            }

            if (!linkedEntityResult) {
                // Throw an error to signify to Excel that resolution/refresh of the requested linkedEntityId failed.
                throw notAvailableError;
            }

            result.entities.push(linkedEntityResult);
        }

        return result;
    } catch (error) {
        console.error(error);
        throw notAvailableError;
    }
}

L’exemple de code suivant montre la fonction d’assistance pour créer une valeur de cellule d’entité liée au produit. Cette fonction est appelée par le code contosoLoadService précédent pour créer une entité liée pour un ID de produit spécifique. Remarques sur le code suivant :

• Il utilise les mêmes paramètres que l’exemple précédent insertProduct pour les typepropriétés , idet text .
• Il inclut des propriétés supplémentaires spécifiques au domaine de données Products , telles que Product Name et Unit Price.
• Il crée une entité liée imbriquée différée pour la catégorie du produit. Les propriétés de la catégorie ne sont pas demandées tant qu’elles ne sont pas nécessaires.

/** Helper function to create a linked entity from product properties. */
function makeProductLinkedEntity(productID: string): any {
    // Search the product data in the data source for a matching product ID.
    const product = getProduct(productID);
    if (product === null) {
        // Return null if no matching product is found.
        return null;
    }

    const productLinkedEntity: Excel.LinkedEntityCellValue = {
        type: "LinkedEntity",
        text: product.productName,
        id: {
            entityId: product.productID,
            domainId: productsDomainId,
            serviceId: addinDomainServiceId,
            culture: defaultCulture
        },
        properties: {
            "Product ID": {
                type: "String",
                basicValue: product.productID
            },
            "Product Name": {
                type: "String",
                basicValue: product.productName
            },
            "Quantity Per Unit": {
                type: "String",
                basicValue: product.quantityPerUnit
            },
            // Add Unit Price as a formatted number.
            "Unit Price": {
                type: "FormattedNumber",
                basicValue: product.unitPrice,
                numberFormat: "$* #,##0.00"
            },
            Discontinued: {
                type: "Boolean",
                basicValue: product.discontinued
            }
        },
        layouts: {
            compact: {
                icon: "ShoppingBag"
            },
            card: {
                title: { property: "Product Name" },
                sections: [
                    {
                        layout: "List",
                        properties: ["Product ID"]
                    },
                    {
                        layout: "List",
                        title: "Quantity and price",
                        collapsible: true,
                        collapsed: false,
                        properties: ["Quantity Per Unit", "Unit Price"]
                    },
                    {
                        layout: "List",
                        title: "Additional information",
                        collapsed: true,
                        properties: ["Discontinued"]
                    }
                ]
            }
        }
    };

    // Add image property to the linked entity and then add it to the card layout.
    if (product.productImage) {
        productLinkedEntity.properties["Image"] = {
            type: "WebImage",
            address: product.productImage
        };
        productLinkedEntity.layouts.card.mainImage = { property: "Image" };
    }

    // Add a deferred nested linked entity for the product category.
    const category = getCategory(product.categoryID.toString());
    if (category) {
        productLinkedEntity.properties["Category"] = {
            type: "LinkedEntity",
            text: category.categoryName,
            id: {
                entityId: category.categoryID.toString(),
                domainId: categoriesDomainId,
                serviceId: addinDomainServiceId,
                culture: defaultCulture
            }
        };

        // Add nested product category to the card layout.
        productLinkedEntity.layouts.card.sections[0].properties.push("Category");
    }

    // Add a deferred nested linked entity for the supplier.
    const supplier = getSupplier(product.supplierID.toString());
    if (supplier) {
        productLinkedEntity.properties["Supplier"] = {
            type: "LinkedEntity",
            text: supplier.companyName,
            id: {
                entityId: supplier.supplierID.toString(),
                domainId: suppliersDomainId,
                serviceId: addinDomainServiceId,
                culture: defaultCulture
            }
        };

        // Add nested product supplier to the card layout.
        productLinkedEntity.layouts.card.sections[2].properties.push("Supplier");
    }

    return productLinkedEntity;
}

L’exemple de code suivant montre la fonction d’assistance pour créer une valeur de cellule d’entité liée de catégorie. Cette fonction est appelée par le code contosoLoadService précédent pour créer une entité liée pour un ID de catégorie spécifique.

/** Helper function to create a linked entity from category properties. */
function makeCategoryLinkedEntity(categoryID: string): any {
    // Search the sample JSON category data for a matching category ID.
    const category = getCategory(categoryID);
    if (category === null) {
        // Return null if no matching category is found.
        return null;
    }

    const categoryLinkedEntity: Excel.LinkedEntityCellValue = {
        type: "LinkedEntity",
        text: category.categoryName,
        id: {
            entityId: category.categoryID,
            domainId: categoriesDomainId,
            serviceId: addinDomainServiceId,
            culture: defaultCulture
        },
        properties: {
            "Category ID": {
                type: "String",
                basicValue: category.categoryID,
                propertyMetadata: {
                    // Exclude the category ID property from the card view and auto-complete.
                    excludeFrom: {
                        cardView: true,
                        autoComplete: true
                    }
                }
            },
            "Category Name": {
                type: "String",
                basicValue: category.categoryName
            },
            Description: {
                type: "String",
                basicValue: category.description
            }
        },
        layouts: {
            compact: {
                icon: "Branch"
            }
        }
    };

    return categoryLinkedEntity;
}

L’exemple de code suivant montre la fonction d’assistance pour créer une valeur de cellule d’entité liée au fournisseur. Cette fonction est appelée par le code contosoLoadService précédent pour créer une entité liée pour un ID de fournisseur spécifique.

/** Helper function to create linked entity from supplier properties. */
function makeSupplierLinkedEntity(supplierID: string): any {
    // Search the sample JSON category data for a matching supplier ID.
    const supplier = getSupplier(supplierID);
    if (supplier === null) {
        // Return null if no matching supplier is found.
        return null;
    }

    const supplierLinkedEntity: Excel.LinkedEntityCellValue = {
        type: "LinkedEntity",
        text: supplier.companyName,
        id: {
            entityId: supplier.supplierID,
            domainId: suppliersDomainId,
            serviceId: addinDomainServiceId,
            culture: defaultCulture
        },
        properties: {
            "Supplier ID": {
                type: "String",
                basicValue: supplier.supplierID
            },
            "Company Name": {
                type: "String",
                basicValue: supplier.companyName
            },
            "Contact Name": {
                type: "String",
                basicValue: supplier.contactName
            },
            "Contact Title": {
                type: "String",
                basicValue: supplier.contactTitle
            }
        },
        cardLayout: {
            title: { property: "Company Name" },
            sections: [
                {
                    layout: "List",
                    properties: ["Supplier ID", "Company Name", "Contact Name", "Contact Title"]
                }
            ]
        }
    };

    return supplierLinkedEntity;
}

L’exemple de code suivant contient des exemples de données que vous pouvez utiliser avec les exemples de code précédents.

/// Sample product data.
const products = [
    {
        productID: "P1",
        productName: "Chai",
        supplierID: "S1",
        categoryID: "C1",
        quantityPerUnit: "10 boxes x 20 bags",
        unitPrice: 18,
        discontinued: false,
        productImage: "https://upload.wikimedia.org/wikipedia/commons/thumb/0/04/Masala_Chai.JPG/320px-Masala_Chai.JPG"
    }
];

/// Sample product category data.
const categories = [
    {
        categoryID: "C1",
        categoryName: "Beverages",
        description: "Soft drinks, coffees, teas, beers, and ales"
    }];

/// Sample product supplier data.
const suppliers = [
    {
        supplierID: "S1",
        companyName: "Exotic Liquids",
        contactName: "Ema Vargova",
        contactTitle: "Purchasing Manager"
    }];

Options d’actualisation des données

Lorsque vous inscrivez un domaine de données, les utilisateurs peuvent l’actualiser manuellement à tout moment, par exemple en choisissantActualiser toutes lesdonnées>. Vous pouvez également configurer un ou plusieurs des modes d’actualisation suivants.

• manual: actualise les données uniquement lorsque l’utilisateur choisit d’actualiser. Il s’agit du mode par défaut. L’actualisation manuelle est toujours disponible, même lorsque le mode d’actualisation est défini sur onLoad ou periodic.
• onLoad: actualise les données lorsque le domaine de données est inscrit, ce qui se produit généralement lorsque le complément se charge. Après cela, les utilisateurs actualisent les données manuellement. Si vous souhaitez actualiser les données lorsque le classeur s’ouvre, configurez votre complément pour qu’il soit chargé sur l’ouverture du document. Pour plus d’informations, voir Exécuter du code dans votre complément Office lorsque le document s’ouvre.
• periodic: actualise les données lorsque le domaine de données est inscrit, puis les actualise à nouveau à un intervalle spécifié. Par exemple, vous pouvez actualiser toutes les 300 secondes, ce qui est la valeur minimale. Excel arrondit l’intervalle à la minute la plus proche, car il ne s’actualise que par incréments de minutes entières.

L’exemple de code suivant montre comment configurer un domaine de données pour l’actualiser lors du chargement, puis continuer à l’actualiser toutes les 5 minutes.

const productsDomain: Excel.LinkedEntityDataDomainCreateOptions = {
    dataProvider: domainDataProvider,
    id: "products",
    name: "Products",
    // ID of the custom function that is called on demand by Excel to resolve or refresh linked entity cell values of this data domain.
    loadFunctionId: loadFunctionId,
    // periodicRefreshInterval is only required when supportedRefreshModes contains "Periodic".
    periodicRefreshInterval: 300, // equivalent to 5 minutes.
    // Manual refresh mode is always supported, even if unspecified.
    supportedRefreshModes: [
        Excel.LinkedEntityDataDomainRefreshMode.periodic,
        Excel.LinkedEntityDataDomainRefreshMode.onLoad
    ]
};

Vous pouvez également demander par programmation une actualisation sur un domaine de données d’entité liée à l’aide de l’une des méthodes suivantes.

• LinkedEntityDataDomain.refresh() - Actualise tous les LinkedEntityCellValue objets du domaine de données d’entité liée.
• LinkedEntityDataDomainCollection.refreshAll() - Actualise tous les LinkedEntityCellValue objets de tous les domaines de données d’entité liée dans la collection.

Les méthodes d’actualisation demandent une actualisation qui se produit de manière asynchrone. Pour déterminer les résultats de l’actualisation, écoutez l’événement onRefreshCompleted . L’exemple de code suivant montre un exemple d’écoute de l’événement onRefreshCompleted .

await Excel.run(async (context) => {
    const dataDomains = context.workbook.linkedEntityDataDomains;
    dataDomains.onRefreshCompleted.add(onLinkedEntityDomainRefreshed);

    await context.sync();
});

async function onLinkedEntityDomainRefreshed(eventArgs: Excel.LinkedEntityDataDomainRefreshCompletedEventArgs): Promise<any> {
    console.log(`Linked entity domain refreshed: ${eventArgs.id}`);
    console.log(`Refresh status: ${eventArgs.refreshed}`);
    console.log(`Refresh error: ${eventArgs.errors}`);
    return null;
}

Gestion des erreurs avec le service de chargement d’entités liées

Quand Excel appelle votre complément pour obtenir des données pour une valeur de cellule d’entité liée, une erreur peut se produire. Si Excel ne peut pas se connecter à votre complément, par exemple quand le complément n’est pas chargé, Excel affiche l’erreur #CONNECT! à l’utilisateur.

Si votre fonction de service de chargement d’entité liée rencontre une erreur, elle doit lever l’erreur notAvailableError . Cela entraîne la présentation #CONNECT! d’Excel à l’utilisateur.

Le code suivant montre comment gérer une erreur dans une fonction de service de chargement d’entité liée.

async function contosoLoadService(request: any): Promise<any> {
    const notAvailableError = new CustomFunctions.Error(CustomFunctions.ErrorCode.notAvailable);
    try {
        // Create and return a new linked entity cell value.
        let linkedEntityResult = ...
      ...
        if (!linkedEntityResult) {
            // Throw an error to signify to Excel that resolution or refresh of the requested linkedEntityId failed.
            throw notAvailableError;
        }
      ...
    } catch (error) {
        console.error(error);
        throw notAvailableError;
    }
}

Débogage du service de chargement d’entité liée

Vous pouvez déboguer la plupart des fonctionnalités de complément d’entité liée en suivant les instructions fournies dans Vue d’ensemble du débogage des compléments Office. Toutefois, la fonction de service de chargement d’entité liée peut s’exécuter dans un runtime partagé ou dans un runtime JavaScript uniquement, également appelé runtime de fonctions personnalisées. Si vous implémentez la fonction dans un runtime JavaScript uniquement, utilisez le débogage de fonctions personnalisées dans un runtime non partagé.

La fonction de service de chargement d’entité liée utilise l’architecture des fonctions personnalisées, quel que soit le runtime que vous utilisez. Toutefois, il existe des différences significatives par rapport aux fonctions personnalisées standard.

Les fonctions de service de chargement d’entités liées présentent les différences suivantes par rapport aux fonctions personnalisées :

• Elles ne sont pas utilisées par les utilisateurs finaux dans les formules.
• Ils ne prennent pas en charge les balises @streaming JSDoc ou @volatile. L’utilisateur verra une erreur #CALC ! si ces balises sont utilisées.

Les fonctions de service de chargement d’entités liées présentent les similitudes suivantes avec les fonctions personnalisées :

• Ils utilisent le nommage et la localisation des fonctions personnalisées.
• Ils utilisent la même approche de gestion des erreurs.

Comportement dans Excel 2019 et versions antérieures

Si quelqu’un ouvre une feuille de calcul avec des valeurs de cellule d’entité liée sur une version antérieure d’Excel qui ne prend pas en charge les valeurs de cellule d’entité liée, Excel affiche les valeurs de cellule sous forme d’erreurs. Ce comportement est inhérent au produit. Ce comportement est également la raison pour laquelle vous définissez sur basicTypeError et sur basicValue#VALUE! chaque fois que vous insérez ou mettez à jour une valeur de cellule d’entité liée. Cette erreur est le secours utilisé par Excel sur les versions antérieures.

Meilleures pratiques

• N’utilisez pas de points d’exclamation dans les entityID valeurs ou domainId .
• Inscrivez des domaines de données d’entité liée dans votre Office.onReady code d’initialisation afin que les utilisateurs puissent actualiser les valeurs des cellules d’entité liée dès le chargement du complément.
• Après avoir publié votre complément, ne modifiez pas les ID de domaine de données d’entité liée. Des ID cohérents sur les mêmes objets logiques facilitent les performances.
• Fournissez toujours la propriété lors de la text création d’une nouvelle valeur de cellule d’entité liée. Cette valeur s’affiche pendant qu’Excel appelle votre fonction de fournisseur de données pour obtenir les valeurs de propriété restantes. Sinon, l’utilisateur voit une cellule vide jusqu’à ce que les données soient récupérées.

Voir aussi

• Vue d’ensemble des types de données dans Excel de données
• Utiliser des types de données dans les compléments Excel
• Utiliser des cartes avec des types de données de valeur de cellule
• Ajouter des propriétés aux valeurs de base des cellules Excel
• Fonctions personnalisées et types de données