Criar tipos de dados de entidades ligadas em suplementos do Excel

Utilize valores de células de entidade ligadas quando o suplemento do Excel precisar de mostrar dados externos sem armazenar o conjunto de dados completo no livro. Por exemplo, pode mostrar um produto, cliente ou fornecedor numa célula, abrir um card avançado para obter detalhes e carregar dados aninhados apenas quando o Excel precisar.

O Excel utiliza o mesmo padrão para tipos de dados ligados incorporados, como Ações e Geografia. Este artigo mostra como criar o seu próprio fornecedor de dados num suplemento do Excel.

Neste artigo, você aprenderá a:

• Registar domínios de dados de entidades ligadas.
• Inserir valores de células de entidade ligadas a partir de um comando ou função personalizada.
• Implementar uma função do serviço de carregamento de entidades ligadas.
• Configurar a atualização e o processamento de erros.

Antes de começar, reveja estes artigos relacionados:

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

O que fazem os valores das células de entidade ligadas

Os valores das células de entidade ligadas ligam as células do livro a uma origem de dados externa e apresentam o resultado como uma entidade card.

Tal como os valores normais das entidades, pode referenciar valores de células de entidade ligadas em fórmulas.

Em comparação com os valores de entidade regulares, os valores das células de entidade ligadas oferecem estas vantagens.

• Os valores de células de entidades ligadas aninhadas não são obtidos até que o utilizador ou a folha de cálculo os referencie. Isto ajuda a reduzir o tamanho do ficheiro e a melhorar o desempenho do livro.
• O Excel coloca em cache valores de células de entidade ligadas para que múltiplas células possam referenciar o mesmo valor de forma eficiente.

Principais termos

Utilize os seguintes termos ao longo deste artigo.

• Domínio de dados de entidade ligada – um domínio de dados de entidade ligada descreve a categoria geral à qual uma entidade pertence. Alguns exemplos são funcionários, organizações ou carros.
• Valor da célula da entidade ligada – uma instância criada a partir de um domínio de dados. Um exemplo é um valor de funcionário para alguém chamado Joe. Pode ser apresentado como um valor de entidade card.
• Fornecedor de dados – o fornecedor de dados é reconhecido pelo Excel como a origem de dados de um ou mais domínios de dados de entidades ligadas registados.
• Função do serviço de carregamento de entidades ligadas – cada domínio de dados de entidade ligada define uma função de serviço de carregamento para atuar como a origem de dados desse domínio. A função do serviço de carregamento de entidades ligadas processa pedidos do Excel para obter valores de células de entidade ligadas para o livro. Pode implementá-lo como uma função personalizada TypeScript ou JavaScript.

Como funciona o fluxo de entidades ligadas

Este diagrama mostra o que acontece depois de o suplemento carregar e inserir um valor de célula de entidade ligada numa célula.

1. O Excel carrega o seu suplemento e o seu suplemento regista todos os domínios de dados de entidades ligadas que suporta. Cada registo inclui o ID de uma função do serviço de carregamento de entidades ligadas. O Excel chama este ID mais tarde para pedir valores de propriedade para o valor da célula de entidade ligada do domínio de dados da entidade ligada. Neste exemplo, está registado um domínio de dados denominado Produtos .
2. O Excel monitoriza cada domínio de dados de entidade ligada registado numa coleção de domínios de dados de entidade ligada. Isto permite ao Excel chamar a função do serviço de carregamento de entidades ligadas quando são necessários dados para um valor de célula de entidade ligada.
3. O suplemento insere um novo valor de célula de entidade ligada na folha de cálculo. Neste exemplo, vai criar um novo valor de célula de entidade ligada para o produto Chai. Normalmente, este passo ocorre quando o utilizador escolhe um botão no seu suplemento que resulta na criação de um ou mais valores de células de entidade ligadas. Quando cria novos valores de célula de entidade ligada, estes contêm apenas uma cadeia de texto inicial que é apresentada na célula. O Excel chama a função do serviço de carregamento de entidades associadas para obter os restantes valores de propriedade. O seu suplemento também pode criar valores de células de entidade ligadas a partir de funções personalizadas.
4. O Excel chama a função do serviço de carregamento de entidades ligadas que registou no passo 1. Isto ocorre sempre que cria um novo valor de célula de entidade ligada ou se ocorrer uma atualização de dados. O Excel chama a função do serviço de carregamento de entidades associadas para obter todos os valores de propriedade.
5. A função do serviço de carregamento de entidades ligadas devolve um valor de célula de entidade ligado atualizado (Excel.LinkedEntityCellValue) para o ID de entidade ligada (Excel.LinkedEntityId) pedido pelo Excel. Normalmente, a função do serviço de carregamento de entidades ligadas consulta uma origem de dados externa para obter os valores e criar o valor da célula de entidade ligada. Neste exemplo, são devolvidos os valores do ID do produto, categoria, quantidade e preço .

As secções seguintes fornecem detalhes adicionais sobre os termos definidos anteriormente neste artigo.

Fornecedor de dados

O seu suplemento é o fornecedor de dados e é reconhecido pelo Excel como a origem de dados de um ou mais domínios de dados registados. O suplemento expõe uma ou mais funções do fornecedor de dados que devolvem dados para valores de células de entidade ligadas. Em Excel.LinkedEntityDataDomainCreateOptions, defina dataProvider para uma cadeia de texto, como Contoso ou o nome do seu suplemento. O nome tem de ser exclusivo no seu suplemento.

Domínios de dados de entidades ligadas

O fornecedor de dados (o seu suplemento) regista um ou mais domínios de dados. Um domínio de dados descreve uma entidade para o Excel. Por exemplo, um fornecedor de dados pode fornecer os domínios de dados de produtos e categorias . Os domínios têm de ser registados no Excel para que possam funcionar com esses domínios para obter e apresentar valores de células de entidade ligadas e efetuar cálculos.

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

• O nome do fornecedor de dados a que está associado.
• Um ID de domínio para o identificar exclusivamente, como produtos.
• Um nome a apresentar para o utilizador, como Produtos.
• Uma função do serviço de carregamento de entidades ligadas para chamar quando o Excel precisa de um valor de célula de entidade ligada.
• Um modo de atualização especificado e um intervalo que descreve a frequência com que é atualizado.

Um exemplo de um domínio de dados de entidade ligada é o domínio de dados Geografia no Excel que fornece valores de células de entidades ligadas para cidades.

Valor da célula da entidade ligada

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

Uma vez que os valores das células de entidade ligadas estão ligados ao domínio de dados, podem ser atualizados. Além disso, os valores de células de entidade ligada aninhadas não são obtidos, a menos que o utilizador os solicite (por exemplo, visualizar a entidade card). Além disso, os valores das células de entidade aninhadas não são guardados com a folha de cálculo, a menos que sejam referenciados a partir da folha de cálculo (como uma fórmula). Isto reduz o tamanho do ficheiro e melhora o desempenho.

Função do serviço de carregamento de entidades ligadas

Cada domínio de dados requer uma função que o Excel pode chamar quando precisa de valores de células de entidade ligadas. O suplemento fornece o serviço como uma função JavaScript ou TypeScript etiquetada com @linkedEntityLoadService. Recomenda-se criar apenas uma função de serviço de carga para um melhor desempenho. O Excel envia todos os pedidos para valores de células de entidade ligadas como um lote para a função do serviço de carga.

Criar um fornecedor de dados com domínios de dados

As secções seguintes mostram como escrever código TypeScript para um suplemento do Excel que funciona como o fornecedor de dados da Contoso. Neste exemplo, o suplemento fornece três domínios de dados: Produtos, Categorias e Fornecedores.

Registar os domínios de dados

Comece por registar cada domínio de dados suportado pelo suplemento. Neste exemplo, o nome do fornecedor de dados é Contoso e os domínios são Produtos, Categorias e Fornecedores.

Utilize Excel.LinkedEntityDataDomainCreateOptions para definir cada domínio, incluindo a função do serviço de carregamento de entidades ligadas que o Excel deve chamar. Em seguida, adicione cada domínio à coleção Workbook.linkedEntityDataDomains . Registe domínios ao inicializar o seu Suplemento do Office.

O código seguinte regista os domínios de dados 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 ligada

Existem duas formas de inserir um valor de célula de entidade ligada numa célula de folha de cálculo.

• Criar um botão de comando no friso ou um botão no painel de tarefas. Quando o utilizador seleciona o botão, o código insere um valor de célula de entidade ligada.
• Crie uma função personalizada que devolva um valor de célula de entidade ligada.

O exemplo seguinte insere um novo valor de célula de entidade ligada na célula selecionada. Pode chamar este código a partir de um comando do friso ou de um botão no painel de tarefas.

Tenha em atenção os seguintes requisitos:

• Tem de especificar um serviceId de para quaisquer valores de 268436224 células de entidade ligadas que devolver. Isto informa o Excel de que o valor da célula de entidade ligada está associado a um suplemento do Excel.
• Tem de especificar um culture. O Excel transmite este valor à função do serviço de carregamento de entidades ligadas para que possa manter a cultura original quando o livro é aberto numa cultura diferente.
• A text propriedade é apresentada ao utilizador na célula enquanto o valor de dados da entidade ligada é atualizado. Isto impede que o utilizador 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 seguinte exemplo de código mostra como inserir um valor de célula de entidade ligada com uma função personalizada. Um utilizador pode obter um valor de célula de entidade ligada ao introduzir =CONTOSO.GETPRODUCTBYID("productid") em qualquer célula. As notas do exemplo de código anterior também se aplicam a esta.

/**
 * 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 do serviço de carregamento de entidades ligadas

O suplemento tem de fornecer uma função do serviço de carregamento de entidades ligadas para processar pedidos do Excel quando são necessários valores de propriedade para quaisquer valores de células de entidade ligadas. A função é identificada com a @linkedEntityLoadService etiqueta JSDoc.

O seguinte exemplo de código mostra como criar uma função que processa pedidos de dados do Excel para os domínios de dados Produtos e Categorias. Notas sobre o seguinte código:

• Utiliza funções auxiliares para criar os valores das células da entidade ligada. Esse código é apresentado mais tarde.
• Se ocorrer um erro, gera um CustomFunctions.ErrorCode.notAvailable erro. Este erro é #CONNECT! apresentado na célula que o utilizador vê.

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

O seguinte exemplo de código mostra a função auxiliar para criar um valor de célula de entidade ligada a um produto. Esta função é chamada pelo código contosoLoadService anterior para criar uma entidade ligada para um ID de produto específico. Notas sobre o seguinte código:

• Utiliza as mesmas definições do exemplo anterior insertProduct para as typepropriedades , ide text .
• Inclui propriedades adicionais específicas do domínio de dados Produtos , como Product Name e Unit Price.
• Cria uma entidade ligada aninhada diferida para a categoria do produto. As propriedades da categoria não são pedidas até serem 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 seguinte exemplo de código mostra a função auxiliar para criar um valor de célula de entidade ligada de categoria. Esta função é chamada pelo código contosoLoadService anterior para criar uma entidade ligada para um ID de categoria específico.

/** 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 seguinte exemplo de código mostra a função auxiliar para criar um valor de célula de entidade associada a um fornecedor. Esta função é chamada pelo código contosoLoadService anterior para criar uma entidade ligada para um ID de fornecedor específico.

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

O seguinte exemplo de código contém dados de exemplo que pode utilizar com os exemplos 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 regista um domínio de dados, os utilizadores podem atualiá-lo manualmente em qualquer altura, tal como ao selecionar AtualizarTodos osDados>. Também pode configurar um ou mais dos seguintes modos de atualização.

• manual: atualiza os dados apenas quando o utilizador opta 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 é registado, o que normalmente acontece quando o suplemento é carregado. Depois disso, os utilizadores atualizam os dados manualmente. Se quiser atualizar os dados quando o livro for aberto, configure o suplemento para carregar no documento aberto. Para obter mais informações, consulte Executar código no seu Suplemento do Office quando o documento for aberto.
• periodic: atualiza os dados quando o domínio de dados é registado e, em seguida, atualiza-os novamente num intervalo especificado. Por exemplo, pode atualizar a cada 300 segundos, que é o valor mínimo. O Excel arredonda o intervalo até ao minuto mais próximo, uma vez que é atualizado apenas em incrementos de minuto inteiro.

O seguinte exemplo de código mostra como configurar um domínio de dados para atualizar no carregamento e, em seguida, 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
    ]
};

Também pode pedir através de programação uma atualização num domínio de dados de entidade ligada através de um dos seguintes métodos.

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

Os métodos de atualização pedem uma atualização que ocorre de forma assíncrona. Para determinar os resultados da atualização, ouça o onRefreshCompleted evento. O seguinte exemplo de código 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;
}

Processamento de erros com o serviço de carregamento de entidades ligadas

Quando o Excel chama o seu suplemento para obter dados para um valor de célula de entidade ligada, pode ocorrer um erro. Se o Excel não conseguir ligar-se ao seu suplemento, como quando o suplemento não está carregado, o Excel apresenta o #CONNECT! erro ao utilizador.

Se a função do serviço de carregamento de entidades ligadas encontrar um erro, deverá gerar o notAvailableError erro. Isto faz com que o Excel mostre #CONNECT! ao utilizador.

O código seguinte mostra como lidar com um erro numa função do serviço de carregamento de entidades ligadas.

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

Depurar o serviço de carregamento de entidades ligadas

Pode depurar a maioria das funcionalidades de suplementos de entidades ligadas ao seguir a documentação de orientação em Descrição geral da depuração de Suplementos do Office. No entanto, a função do serviço de carregamento de entidades ligadas pode ser executada num runtime partilhado ou num runtime apenas javaScript, também conhecido como runtime de funções personalizadas. Se implementar a função num runtime apenas em JavaScript, utilize a depuração de Funções personalizadas num runtime não partilhado.

A função do serviço de carregamento de entidades ligadas utiliza a arquitetura de funções personalizadas, independentemente do runtime que utilizar. No entanto, existem diferenças significativas em função personalizada regular.

As funções do serviço de carregamento de entidades ligadas têm as seguintes diferenças em função personalizada:

• Não parecem ser utilizadores finais para utilização em fórmulas.
• Não suportam as etiquetas @streaming JSDoc ou @volatile. O utilizador verá um erro #CALC! se estas etiquetas forem utilizadas.

As funções do serviço de carregamento de entidades ligadas têm as seguintes semelhanças com funções personalizadas:

• Utilizam a nomenclatura e localização das Funções personalizadas.
• Utilizam a mesma abordagem de processamento de erros.

Comportamento no Excel 2019 e anterior

Se alguém abrir uma folha de cálculo com valores de célula de entidade ligada numa versão mais antiga do Excel que não suporte valores de células de entidade ligada, o Excel mostra os valores das células como erros. Este é o comportamento padrão. Este comportamento também é o motivo pelo qual define o basicType como Error e o basicValue para #VALUE! sempre que insere ou atualiza um valor de célula de entidade ligada. Este erro é a contingência que o Excel utiliza em versões mais antigas.

Práticas recomendadas

• Não utilize marcas de exclamação nos entityID valores ou domainId .
• Registe domínios de dados de entidades ligadas no código Office.onReady de inicialização para que os utilizadores possam atualizar os valores das células de entidade ligadas assim que o suplemento for carregado.
• Depois de publicar o suplemento, não altere os IDs de domínio de dados da entidade ligada. Os IDs consistentes nos mesmos objetos lógicos ajudam no desempenho.
• Forneça sempre a text propriedade ao criar um novo valor de célula de entidade ligada. Este valor é apresentado enquanto o Excel chama a função de fornecedor de dados para obter os restantes valores de propriedade. Caso contrário, o utilizador vê uma célula em branco até que os dados sejam obtidos.

Confira também

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