Criar tipos de dados de entidade vinculados em suplementos do Excel

Use valores de células de entidade vinculadas quando o suplemento do Excel precisar mostrar dados externos sem armazenar o conjunto de dados completo na pasta de trabalho. Por exemplo, você pode mostrar um produto, cliente ou fornecedor em uma célula, abrir um rich card para obter detalhes e carregar dados aninhados somente quando o Excel precisar deles.

O Excel usa o mesmo padrão para tipos de dados vinculados internos, como Ações e Geografia. Este artigo mostra como criar seu próprio provedor de dados em um suplemento do Excel.

Neste artigo, você aprenderá a:

• Registre domínios de dados de entidade vinculados.
• Inserir valores de célula de entidade vinculada a partir de um comando ou função personalizada.
• Implemente uma função de serviço de carregamento de entidade vinculada.
• Configure a atualização e o tratamento de erros.

Antes de começar, leia estes artigos relacionados:

• Visão geral dos tipos de dados em suplementos do Excel
• Usar tipos de dados em suplementos do Excel
• Usar cartões com tipos de dados de valor de célula
• Adicionar propriedades aos valores de células básicas do Excel

O que os valores de células de entidade vinculada fazem

Valores de célula de entidade vinculada conectam células de pasta de trabalho a uma fonte de dados externa e exibem o resultado como uma entidade card.

Assim como os valores de entidade regulares, você pode fazer referência a valores de células de entidade vinculada em fórmulas.

Em comparação com os valores de entidade regulares, os valores de célula de entidade vinculada oferecem essas vantagens.

• Os valores de células de entidade vinculada aninhada não são recuperados até que o usuário ou a planilha faça referência a eles. Isso ajuda a reduzir o tamanho do arquivo e melhorar o desempenho da pasta de trabalho.
• O Excel armazena em cache valores de células de entidades vinculadas para que várias células possam fazer referência ao mesmo valor com eficiência.

Principais termos

Use os seguintes termos ao longo deste artigo.

• Domínio de dados de entidade vinculada – Um domínio de dados de entidade vinculado descreve a categoria geral à qual uma entidade pertence. Alguns exemplos são funcionários, organizações ou carros.
• Valor da célula da entidade vinculada – uma instância criada a partir de um domínio de dados. Um exemplo é o valor de funcionário de alguém chamado Joe. Ele pode ser exibido como um card de valor de entidade.
• Provedor de dados – o provedor de dados é reconhecido pelo Excel como a fonte de dados para um ou mais domínios de dados de entidade vinculada registrados.
• Função de serviço de carregamento de entidade vinculada – Cada domínio de dados de entidade vinculada define uma função de serviço de carregamento para atuar como fonte de dados para esse domínio. A função de serviço de carregamento de entidade vinculada manipula solicitações do Excel para obter valores de célula de entidade vinculada para a pasta de trabalho. Você a implementa como uma função personalizada TypeScript ou JavaScript.

Como funciona o fluxo de entidades vinculadas

Este diagrama mostra o que acontece depois que o suplemento carrega e insere um valor de célula de entidade vinculada em uma célula.

1. O Excel carrega seu suplemento, e ele registra todos os domínios de dados de entidade vinculados com suporte. Cada registro inclui a ID de uma função de serviço de carregamento de entidade vinculada. O Excel chama essa ID posteriormente para solicitar valores de propriedade para o valor da célula de entidade vinculada do domínio de dados de entidade vinculada. Neste exemplo, um domínio de dados chamado Produtos está registrado.
2. O Excel rastreia cada domínio de dados de entidade vinculada registrado em uma coleção de domínio de dados de entidade vinculada. Isso permite que o Excel chame sua função de serviço de carregamento de entidade vinculada quando os dados forem necessários para um valor de célula de entidade vinculada.
3. O suplemento insere um novo valor de célula de entidade vinculada na planilha. Neste exemplo, você cria um novo valor de célula de entidade vinculada para o produto Chai. Essa etapa geralmente ocorre quando o usuário escolhe um botão em seu suplemento que resulta na criação de um ou mais valores de células de entidade vinculadas. Quando você cria novos valores de célula de entidade vinculada, eles contêm apenas uma cadeia de texto inicial que é exibida na célula. O Excel chama sua função de serviço de carregamento de entidade vinculada para obter os valores de propriedade restantes. Seu suplemento também pode criar valores de células de entidades vinculadas a partir de funções personalizadas.
4. O Excel chama a função de serviço de carregamento de entidade vinculada que você registrou na etapa 1. Isso ocorre sempre que você cria um novo valor de célula de entidade vinculada ou se ocorre uma atualização de dados. O Excel chama sua função de serviço de carregamento de entidade vinculada para obter todos os valores de propriedade.
5. A função de serviço de carregamento de entidade vinculada retorna um valor de célula de entidade vinculada atualizado (Excel.LinkedEntityCellValue) para a ID de entidade vinculada (Excel.LinkedEntityId) solicitada pelo Excel. Normalmente, sua função de serviço de carregamento de entidade vinculada consulta uma fonte de dados externa para obter os valores e criar o valor da célula de entidade vinculada. Neste exemplo, os valores de ID do produto, categoria, quantidade e preço são retornados.

As seções a seguir fornecem detalhes adicionais sobre os termos definidos anteriormente neste artigo.

Provedor de dados

Seu suplemento é o provedor de dados e é reconhecido pelo Excel como a fonte de dados para um ou mais domínios de dados registrados. Seu suplemento expõe uma ou mais funções de provedor de dados que retornam dados para valores de células de entidades vinculadas. No Excel.LinkedEntityDataDomainCreateOptions, defina dataProvider como uma cadeia de texto como Contoso ou o nome do seu suplemento. O nome deve ser exclusivo em seu suplemento.

Domínios de dados de entidade vinculados

O provedor de dados (seu suplemento) registra um ou mais domínios de dados. Um domínio de dados descreve uma entidade para o Excel. Por exemplo, um provedor de dados pode fornecer os domínios de dados de produtos e categorias . Os domínios devem ser registrados no Excel para que ele possa trabalhar com esses domínios para recuperar e exibir valores de células de entidade vinculada e realizar cálculos.

Um domínio de dados descreve ao Excel os seguintes atributos:

• O nome do provedor de dados ao qual ele está associado.
• Um ID de domínio para identificá-lo exclusivamente, como produtos.
• Um nome de exibição para o usuário, como Produtos.
• Uma função de serviço de carregamento de entidade vinculada a ser chamada quando o Excel precisar de um valor de célula de entidade vinculada.
• Um modo de atualização especificado e um intervalo que descreve a frequência com que ele é atualizado.

Um exemplo de domínio de dados de entidade vinculada é o domínio de dados Geography no Excel que fornece valores de célula de entidade vinculada para cidades.

Valor da célula de entidade vinculada

Um valor de célula de entidade vinculada é uma instância criada a partir de um domínio de dados. Um exemplo é um valor para Seattle, do domínio de dados de Geografia. Ele exibe um card de valor de entidade como valores de células de entidade regulares.

Como os valores de célula de entidade vinculada estão vinculados ao domínio de dados, eles podem ser atualizados. Ao implementar valores de célula de entidade vinculada aninhada, observe os seguintes comportamentos que reduzem o tamanho do arquivo para melhorar o desempenho.

• Os valores de células de entidade aninhadas e vinculadas não são recuperados, a menos que o usuário os solicite, por exemplo, exibindo o card da entidade.
• Valores de células de entidades aninhadas e vinculadas não são salvos com a planilha, a menos que a planilha faça referência a eles, como uma fórmula.

Função de serviço de carregamento de entidade vinculada

Cada domínio de dados requer uma função que o Excel pode chamar quando precisar de valores de célula de entidade vinculada. Implemente o serviço como uma função JavaScript ou TypeScript marcada com @linkedEntityLoadService. É recomendável criar apenas uma função de serviço de carga para obter um melhor desempenho. O Excel envia todas as solicitações de valores de célula de entidade vinculada como um lote para a função de serviço de carregamento.

Criar um provedor de dados com domínios de dados

As seções a seguir mostram como escrever código TypeScript para um suplemento do Excel que atua como o provedor de dados para a Contoso. Neste exemplo, o suplemento fornece três domínios de dados: Produtos, Categorias e Fornecedores.

Registrar os domínios de dados

Comece registrando cada domínio de dados compatível com seu suplemento. Neste exemplo, o nome do provedor de dados é Contoso e os domínios são Produtos, Categorias e Fornecedores.

Use Excel.LinkedEntityDataDomainCreateOptions para definir cada domínio, incluindo a função de serviço de carregamento de entidade vinculada que o Excel deve chamar. Em seguida, adicione cada domínio à coleção Workbook.linkedEntityDataDomains . Registrar domínios ao inicializar seu suplemento do Office.

O código a seguir registra os domínios de dados de Produtos, Categorias e Fornecedores .

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();
    });
});

Inserir um valor de célula de entidade vinculada

Há duas maneiras de inserir um valor de célula de entidade vinculada em uma célula de planilha.

• Crie um botão de comando na faixa de opções ou um botão no painel de tarefas. Quando o usuário seleciona o botão, seu código insere um valor de célula de entidade vinculada.
• Crie uma função personalizada que retorne um valor de célula de entidade vinculada.

O exemplo a seguir insere um novo valor de célula de entidade vinculada na célula selecionada. Você pode chamar esse código de um comando da faixa de opções ou de um botão no painel de tarefas.

Lembre-se dos seguintes requisitos:

• Você deve especificar um serviceId de para todos os valores de célula de 268436224 entidade vinculada que você retornar. Isso informa ao Excel que o valor da célula de entidade vinculada está associado a um suplemento do Excel.
• Você deve especificar um culturearquivo . O Excel passa esse valor para sua função de serviço de carregamento de entidade vinculada para que você possa manter a cultura original quando a pasta de trabalho for aberta em uma cultura diferente.
• A text propriedade é exibida para o usuário na célula enquanto o valor dos dados da entidade vinculada é atualizado. Isso impede que o usuário veja uma célula em branco enquanto a atualização é concluída.

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();
    });
}

O exemplo de código a seguir mostra como inserir um valor de célula de entidade vinculada usando uma função personalizada. Um usuário pode obter um valor de célula de entidade vinculada inserindo =CONTOSO.GETPRODUCTBYID("productid") em qualquer célula. As observações para o exemplo de código anterior também se aplicam a este.

/**
 * 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;
}

Implementar a função de serviço de carregamento de entidade vinculada

O suplemento deve fornecer uma função de serviço de carregamento de entidade vinculada para lidar com solicitações do Excel quando valores de propriedade forem necessários para qualquer valor de célula de entidade vinculada. A função é identificada com a @linkedEntityLoadService tag JSDoc.

Os exemplos de código a seguir mostram como:

• Crie funções auxiliares usadas pela função de serviço de carregamento para gerar LinkedEntityCellValue objetos.
• Crie uma função para lidar com solicitações de dados do Excel para os domínios de dados Produtos, Categorias e Fornecedores .

Criar funções auxiliares

O exemplo de código a seguir mostra a função auxiliar para criar um valor de célula de entidade vinculado ao produto. Essa função é chamada pela contosoLoadService função de serviço de carregamento para criar uma entidade vinculada para uma ID de produto específica. Observe o seguinte sobre o código.

• Ele usa as mesmas configurações do exemplo anterior insertProduct para as typepropriedades , id, and text .
• Ele inclui propriedades adicionais específicas do domínio de dados Produtos , como Product Name e Unit Price.
• Ela cria uma entidade vinculada aninhada adiada para a categoria do produto. As propriedades da categoria não são solicitadas até que sejam necessárias.

/** 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;
}

O exemplo de código a seguir mostra a função auxiliar para criar um valor de célula de entidade vinculada à categoria. Essa função é chamada pela contosoLoadService função de serviço de carregamento para criar uma entidade vinculada para uma ID de categoria específica.

/** 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;
}

O exemplo de código a seguir mostra a função auxiliar para criar um valor de célula de entidade vinculada ao fornecedor. Essa função é chamada pela contosoLoadService função de serviço de carregamento para criar uma entidade vinculada para uma ID de fornecedor específica.

/** 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;
}

Implementar a função de serviço de carregamento usando as funções auxiliares

O código a seguir mostra uma função de serviço de carregamento de entidade vinculada que chama as funções auxiliares para criar os valores de célula de entidade vinculada. Observe o seguinte sobre o código.

• A função de serviço de carregamento analisa o objeto de entrada para extrair a ID de LinkedEntityLoadServiceRequest domínio e as IDs de entidade. Essas IDs são usadas para identificar a qual domínio de dados uma entidade pertence, para que as funções auxiliares apropriadas possam ser chamadas para criar um valor de célula de entidade vinculada.
• As funções auxiliares criam os objetos completos LinkedEntityCellValue com todas as propriedades preenchidas.
• A função de serviço de carregamento retorna um LinkedEntityLoadServiceResult objeto que contém os valores de célula de entidade vinculada na mesma ordem em que foram solicitados.

// 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 and refresh LinkedEntityCellValue's of that LinkedEntityDataDomain.
 * @customfunction
 * @linkedEntityLoadService
 * @param {any} request Request to resolve and refresh LinkedEntityCellValue objects.
 * @return {any} Resolved or 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) {
            let 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;
    }
}

A amostra de código a seguir contém dados de amostra que você pode usar com as amostras de código anteriores.

/// 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"
    }];

Opções de atualização de dados

Quando você registra um domínio de dados, os usuários podem atualizá-lo manualmente a qualquer momento, por exemplo, escolhendoAtualizar Tudo deDados>. Você também pode configurar um ou mais dos seguintes modos de atualização.

• manual: atualiza os dados somente quando o usuário optar por atualizar. Esse é o modo padrão. A atualização manual está sempre disponível, mesmo quando o modo de atualização está definido como onLoad ou periodic.
• onLoad: atualiza os dados quando o domínio de dados é registrado, o que normalmente acontece quando o suplemento é carregado. Depois disso, os usuários atualizam os dados manualmente. Se você quiser atualizar os dados quando a pasta de trabalho for aberta, configure o suplemento para ser carregado ao abrir o documento. Para obter mais informações, consulte Executar código no Suplemento do Office quando o documento for aberto.
• periodic: atualiza os dados quando o domínio de dados é registrado e, em seguida, os atualiza novamente em um intervalo especificado. Por exemplo, você pode atualizar a cada 300 segundos, que é o valor mínimo. O Excel arredonda o intervalo para cima até o minuto mais próximo porque ele é atualizado apenas em incrementos de minutos inteiros.

O exemplo de código a seguir mostra como configurar um domínio de dados para atualizar ao carregar e continuar a atualizar a cada 5 minutos.

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
    ]
};

Você também pode solicitar programaticamente uma atualização em um domínio de dados de entidade vinculada usando qualquer um dos métodos a seguir.

• LinkedEntityDataDomain.refresh() - Atualiza todos os LinkedEntityCellValue objetos do domínio de dados da entidade vinculada.
• LinkedEntityDataDomainCollection.refreshAll() - Atualiza todos os LinkedEntityCellValue objetos de todos os domínios de dados de entidade vinculados na coleção.

Os métodos de atualização solicitam uma atualização que ocorre de forma assíncrona. Para determinar os resultados da atualização, ouça o onRefreshCompleted evento. A amostra de código a seguir mostra um exemplo de escuta do onRefreshCompleted evento.

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;
}

Consultar valores de células de entidade vinculada

Se você tiver um domínio de entidade vinculada e IDs de entidade, poderá carregá-lo sem adicioná-lo a uma pasta de trabalho chamando o loadLinkedEntityCellValue método. O método é assíncrono e retorna resultados por meio do evento onLinkedEntityCellValueLoaded . Você deve registrar um manipulador de eventos para esse evento antes de chamar loadLinkedEntityCellValue. O objeto LinkedEntityCellValueLoadedEventArgs passado para o manipulador de eventos contém as informações carregadas LinkedEntityCellValue e quaisquer informações de erro.

A amostra de código a seguir mostra como registrar e implementar um manipulador de eventos e chamar loadLinkedEntityCellValue.

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

/**
 * Registers an event handler for the onLinkedEntityCellValueLoaded event.
 * This event occurs when a linked entity cell value has been loaded.
 */
async function registerEvent() {
    await Excel.run(async (context) => {
        const linkedEntityDataDomains = context.workbook.linkedEntityDataDomains;
    
        // Register the event handler
        linkedEntityDataDomains.onLinkedEntityCellValueLoaded.add(handleLinkedEntityLoaded);
    
        await context.sync();
        console.log("Event handler registered successfully. You'll be notified when linked entities are loaded.");
    });
}

/**
 * Event handler that's called when a linked entity cell value is loaded.
 * @param event - The event object containing the loaded LinkedEntityCellValue.
 */
async function handleLinkedEntityLoaded(event: Excel.LinkedEntityCellValueLoadedEventArgs) {
    await Excel.run(async (context) => {
        const loadedLinkedEntityCellValue: Excel.LinkedEntityCellValue = event.linkedEntityCellValue;

        // Queue operations on the loaded entity value here.

        await context.sync();
    });
}

/**
 * Loads a linked entity cell value.
 * @param domainId - The domain specific to the service used for the linked entity cell value.
 * @param entityId - The linked entity cell value's identifier.
 */
async function loadLinkedEntity(domainId: string, entityId: string ) {
  await Excel.run(async (context) => {
    // Specify the linked entity ID to load.
    const linkedEntityId: Excel.LinkedEntityId = {
      entityId: entityId,
      domainId: domainId,
      serviceId: addinDomainServiceId,
      culture: defaultCulture,
    };

    // Load the linked entity cell value.
    context.workbook.linkedEntityDataDomains.loadLinkedEntityCellValue(linkedEntityId);
    await context.sync();

    // The onLinkedEntityCellValueLoaded event occurs once the linked entity cell value is loaded.
  });
}

Tratamento de erros com o serviço de carregamento de entidade vinculado

Quando o Excel chama seu suplemento para obter dados para o valor de uma célula de entidade vinculada, pode ocorrer um erro. Se o Excel não conseguir se conectar ao suplemento, por exemplo, quando o suplemento não estiver carregado, o Excel exibirá o erro para o #CONNECT! usuário.

Se a função de serviço de carregamento de entidade vinculada encontrar um erro, ela deverá lançar um CustomFunctions.Error com .CustomFunctions.ErrorCode.notAvailable Isso faz com que o Excel seja exibido #CONNECT! para o usuário.

O código a seguir mostra como lidar com um erro em uma função de serviço de carregamento de entidade vinculada.

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;
    }
}

Depuração do serviço de carregamento de entidade vinculado

Você pode depurar a maioria das funcionalidades do suplemento de entidade vinculada seguindo as orientações na Visão geral da depuração de Suplementos do Office. No entanto, a função de serviço de carregamento de entidade vinculada pode ser executada em um tempo de execução compartilhado ou em um tempo de execução somente em JavaScript, também conhecido como um tempo de execução de funções personalizadas. Se você implementar a função em um runtime somente JavaScript, use a depuração de funções personalizadas em um runtime não compartilhado.

A função de serviço de carregamento de entidade vinculada usa a arquitetura de funções personalizadas, independentemente do tempo de execução usado. No entanto, existem diferenças significativas em relação às funções personalizadas regulares.

As funções de serviço de carregamento de entidade vinculadas têm as seguintes diferenças em relação às funções personalizadas:

• Eles não aparecem para os usuários finais para uso em fórmulas.
• Eles não suportam as tags @streaming JSDoc ou @volatile. O usuário verá um erro #CALC! se essas marcas forem usadas.

As funções de serviço de carregamento de entidade vinculadas têm as seguintes semelhanças com funções personalizadas:

• Eles usam nomenclatura e localização de funções personalizadas.
• Eles usam a mesma abordagem de tratamento de erros.

Comportamento no Excel 2019 e anterior

Se alguém abrir uma planilha com valores de célula de entidade vinculada em uma versão mais antiga do Excel que não dá suporte a valores de célula de entidade vinculada, o Excel mostrará os valores de célula como erros. Este é o comportamento padrão. Esse comportamento também é o motivo pelo qual você define to basicTypeError e to basicValue#VALUE! sempre que insere ou atualiza um valor de célula de entidade vinculada. Esse erro é o fallback que o Excel usa em versões mais antigas.

Práticas recomendadas

• Não use pontos de exclamação nos entityID valores ou domainId .
• Registre domínios de dados de entidade vinculados em seu Office.onReady código de inicialização para que os usuários possam atualizar os valores das células de entidade vinculadas assim que o suplemento for carregado.
• Depois de publicar seu suplemento, não altere as IDs de domínio de dados de entidade vinculadas. IDs consistentes nos mesmos objetos lógicos ajudam no desempenho.
• Sempre forneça a text propriedade ao criar um novo valor de célula de entidade vinculada. Esse valor é exibido enquanto o Excel chama a função do provedor de dados para obter os valores de propriedade restantes. Caso contrário, o usuário verá uma célula em branco até que os dados sejam recuperados.

Confira também

• Visão geral dos tipos de dados em suplementos do Excel
• Usar tipos de dados em suplementos do Excel
• Usar cartões com tipos de dados de valor de célula
• Adicionar propriedades aos valores de células básicas do Excel
• Funções e tipos de dados personalizados