Créer des valeurs de cellule d’entité liée

Les valeurs de cellule d’entité liée intègrent des types de données provenant de sources de données externes et peuvent afficher les données sous forme de carte d’entité, comme les valeurs d’entité normales. Ils vous permettent de mettre à l’échelle vos types de données pour représenter des jeux de données volumineux sans télécharger toutes les données dans le classeur. Les domaines de données Stocks et Geography disponibles via l’interface utilisateur Excel fournissent des valeurs de cellule d’entité liée. Cet article explique comment créer votre propre fournisseur de données dans un complément Excel pour fournir des valeurs personnalisées aux utilisateurs finaux.

Les valeurs de cellule d’entité liée sont liées à une source de données externe. Ils offrent les avantages suivants par rapport aux valeurs d’entité normales.

• Les valeurs des cellules d’entité liée peuvent s’imbriquer, et les valeurs des cellules d’entité liée imbriquées ne sont pas récupérées tant qu’elles ne sont pas référencées ; soit par l’utilisateur, soit par la feuille de calcul. Cela permet de réduire la taille du fichier et d’améliorer les performances des classeurs.
• Excel utilise un cache pour permettre à différentes cellules de référencer la même valeur de cellule d’entité liée en toute transparence. Cela améliore également les performances des classeurs.

Cet article développe les informations décrites dans les articles suivants. Nous vous recommandons de lire les articles suivants avant d’apprendre à créer vos propres valeurs de cellule d’entité liée.

• Types de données Excel : Titres boursiers et Géographie
• Vue d’ensemble des types de données dans Excel de données
• Valeur d’entité des types de données de l’API JavaScript Excel carte

Concepts clés

Les valeurs de cellule d’entité liée fournissent à l’utilisateur des données liées à partir d’une source de données externe. L’utilisateur peut les afficher en tant que valeur d’entité carte.

Comme les valeurs d’entité normales, les valeurs de cellule d’entité liée peuvent être référencées dans des formules.

Définitions

Les définitions suivantes sont fondamentales pour comprendre comment implémenter vos propres valeurs de cellule d’entité liée.

• 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.

Comment votre complément fournit des valeurs de cellule d’entité liée

Ce diagramme montre les étapes qui se produisent lorsque votre complément est chargé, puis insère une nouvelle valeur de cellule d’entité liée dans une cellule. La description suivante explique ce qui se passe à chaque étape du processus.

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. Cet ID est appelé ultérieurement par Excel 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, une nouvelle valeur de cellule d’entité liée est créée pour le produit Chai. Cela 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.

Remarque

Si Excel a besoin de plusieurs valeurs de cellule d’entité liée, les ID d’entité liée sont transmis en tant que lot à votre fonction de service de chargement d’entité liée. Le service de chargement d’entité liée retourne ensuite un résultat de lot de toutes les valeurs.

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. Le fournisseur de données est identifié par 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 de cet article montrent comment écrire du code TypeScript pour implémenter un complément Excel qui est un fournisseur de données pour Contoso. Il fournit deux domaines de données nommés Products et Categories.

Inscrire les domaines de données

Examinons le code pour inscrire de nouveaux domaines nommés Products and Categories. Le nom du fournisseur de données est Contoso. Lorsque le complément se charge, il inscrit d’abord les domaines de données auprès d’Excel.

Utilisez le type Excel.LinkedEntityDataDomainCreateOptions pour décrire les options souhaitées, notamment la fonction à utiliser comme service de chargement d’entité liée. Ajoutez ensuite le domaine à la collection Workbook.linkedEntityDataDomains . Il est recommandé d’inscrire des domaines lorsque vous initialisez votre complément Office. Le code suivant montre comment inscrire 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 d’une feuille de calcul.

• Créez un bouton de commande dans le ruban ou un bouton dans votre 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 de code suivant montre comment insérer une nouvelle valeur de cellule d’entité liée dans la cellule sélectionnée. Ce code peut être appelé à partir d’un bouton de commande sur le ruban ou d’un bouton dans le volet Office. Remarques sur le code suivant :

• 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 le transmet à 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();
    });
}

Remarque

N’utilisez pas de points d’exclamation dans les entityID valeurs ou domainId .

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, elle génère une CustomFunctions.ErrorCode.notAvailable erreur. Cela 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, l’utilisateur peut l’actualiser manuellement à tout moment, par exemple en choisissant Actualiser tout dans l’onglet Données . Il existe trois modes d’actualisation que vous pouvez spécifier pour votre domaine de données.

• manual- Les données sont actualisées uniquement lorsque l’utilisateur choisit d’actualiser. Il s’agit du mode par défaut. L’actualisation manuelle peut toujours être effectuée par l’utilisateur, même lorsque le mode d’actualisation est défini sur onLoad ou periodic.
• onLoad- Les données sont actualisées lorsque le domaine de données est inscrit (généralement lorsque le complément est chargé). Par la suite, les données sont uniquement actualisées manuellement par l’utilisateur. Si vous souhaitez actualiser les données lorsque le classeur est ouvert, configurez votre complément pour qu’il soit chargé sur le document ouvert. Pour plus d’informations, voir Exécuter du code dans votre complément Office lorsque le document s’ouvre.
• periodic- Les données sont actualisées lorsque le domaine de données est inscrit (généralement lorsque le complément est chargé). Ensuite, les données sont mises à jour en continu après un intervalle de temps spécifié. Par exemple, vous pouvez spécifier que le domaine de données s’actualise toutes les 300 secondes (valeur minimale). Le nombre de secondes est toujours arrondi au nombre de minutes le plus proche, car l’intervalle d’actualisation n’est effectué qu’en minutes.

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, il est possible qu’une erreur se produise. Si Excel ne parvient 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

La plupart des fonctionnalités de complément pour les types de données d’entité liée peuvent être déboguées à l’aide des 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 être implémentée dans un runtime partagé ou un runtime JavaScript uniquement (également connu sous le nom de runtime de fonctions personnalisées). Si vous choisissez d’implémenter la fonction dans un runtime JavaScript uniquement, utilisez les instructions de débogage des 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. Il s’agit du comportement conçu. C’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. Il s’agit de l’erreur qu’Excel utilise comme secours sur les versions antérieures.

Meilleures pratiques

• N’utilisez pas de points d’exclamation dans les entityID valeurs ou domainId .
• Inscrivez les domaines de données d’entité liée dans le code Office.OnReady d’initialisation afin que l’utilisateur dispose immédiatement de fonctionnalités telles que la possibilité d’actualiser les valeurs des cellules d’entité liée.
• 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