Criar valores de células de entidade ligada

2025-05-13

Os valores das células de entidade ligadas integram tipos de dados de origens de dados externas e podem apresentar os dados como uma entidade card, como valores de entidade regulares. Permitem-lhe dimensionar os seus tipos de dados para representar grandes conjuntos de dados sem transferir todos os dados para o livro. Os domínios de dados Ações e Geografia disponíveis através da IU do Excel fornecem valores de células de entidade ligadas. Este artigo explica como criar o seu próprio fornecedor de dados num suplemento do Excel para fornecer valores personalizados aos utilizadores finais.

Os valores das células de entidade ligadas estão ligados a uma origem de dados externa. Fornecem as seguintes vantagens em função dos valores de entidade regulares.

Os valores das células de entidade ligadas podem aninhar e os valores das células de entidade ligada aninhadas não são obtidos até serem referenciados; pelo utilizador ou pela folha de cálculo. Isto ajuda a reduzir o tamanho do ficheiro e a melhorar o desempenho do livro.
O Excel utiliza uma cache para permitir que células diferentes referenciem o mesmo valor de célula de entidade ligada de forma totalmente integrada. Isto também melhora o desempenho do livro.

Este artigo expande as informações descritas nos seguintes artigos. Recomendamos que leia os seguintes artigos antes de aprender a criar os seus próprios valores de células de entidade ligadas.

Principais conceitos

Os valores das células de entidade ligadas fornecem ao utilizador dados ligados a partir de uma origem de dados externa. O utilizador pode vê-los como um valor de entidade card.

Captura de ecrã de um card de dados de valor de entidade para o tipo de dados ligado Seattle Geography na folha de cálculo.

Tal como os valores normais das entidades, os valores das células de entidade ligadas podem ser referenciados em fórmulas.

Captura de ecrã a mostrar a utilização da notação de pontos numa fórmula com =A1. Para apresentar campos para o tipo de dados Geografia de Seattle.

Definições

As seguintes definições são fundamentais para compreender como implementar os seus próprios valores de células de entidade ligadas.

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 o suplemento fornece valores de células de entidade ligadas

Este diagrama mostra os passos que ocorrem quando o suplemento é carregado e, em seguida, insere um novo valor de célula de entidade ligada numa célula. A descrição seguinte explica o que acontece em cada passo do processo.

Diagrama a mostrar os cinco passos de um suplemento para registar domínios de dados e processar pedidos do Excel para obter propriedades de um valor de célula de entidade ligada.

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. Este ID é chamado mais tarde pelo Excel 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 .
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.
O suplemento insere um novo valor de célula de entidade ligada na folha de cálculo. Neste exemplo, é criado um novo valor de célula de entidade ligada para o produto Chai. Normalmente, isto ocorreria a partir do utilizador que 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.
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.
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 .

Observação

Se o Excel precisar de vários valores de células de entidade ligadas, os IDs da entidade ligada são transmitidos como um lote para a função do serviço de carregamento de entidades associadas. Em seguida, o serviço de carregamento de entidades ligadas devolve um resultado em lote de todos os valores.

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. O fornecedor de dados é identificado por 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.

Captura de ecrã de um card de dados de valor de entidade para o tipo de dados ligado Seattle Geography na folha de cálculo.

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 deste artigo mostram como escrever código TypeScript para implementar um suplemento do Excel que é um fornecedor de dados da Contoso. Fornece dois domínios de dados denominados Produtos e Categorias.

Registar os domínios de dados

Vamos analisar o código para registar novos domínios denominados Produtos e Categorias. O nome do fornecedor de dados é Contoso. Quando o suplemento é carregado, regista primeiro os domínios de dados no Excel.

Utilize o tipo Excel.LinkedEntityDataDomainCreateOptions para descrever as opções que pretende, incluindo a função a utilizar como o serviço de carregamento de entidades ligadas. Em seguida, adicione o domínio à coleção Workbook.linkedEntityDataDomains . É recomendado registar domínios quando inicializar o seu Suplemento do Office. O código seguinte mostra como registar 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 numa folha de cálculo.

Crie 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 de código seguinte mostra como inserir um novo valor de célula de entidade ligada na célula selecionada. Este código pode ser chamado a partir de um botão de comando no friso ou de um botão no painel de tarefas. Notas sobre o seguinte código:

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 irá passá-lo para a função do serviço de carregamento de entidades associadas para que possa manter a cultura original quando o livro for 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();
    });
}

Observação

Não utilize marcas de exclamação nos entityID valores ou domainId .

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. Esta ação é apresentada #CONNECT! 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, o utilizador pode atualiá-lo manualmente em qualquer altura, tal como ao selecionar Atualizar Tudo no separador Dados . Existem três modos de atualização que pode especificar para o seu domínio de dados.

manual- Os dados são atualizados apenas quando o utilizador opta por atualizar. Esse é o modo padrão. A atualização manual pode sempre ser efetuada pelo utilizador, mesmo quando o modo de atualização está definido como onLoad ou periodic.
onLoad- Os dados são atualizados quando o domínio de dados é registado (normalmente, quando o suplemento é carregado). Posteriormente, os dados só são atualizados manualmente pelo utilizador. 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- Os dados são atualizados quando o domínio de dados é registado (normalmente, quando o suplemento é carregado). Posteriormente, os dados são atualizados continuamente após um intervalo de tempo especificado. Por exemplo, pode especificar que o domínio de dados é atualizado a cada 300 segundos (que é o valor mínimo). O número de segundos é sempre arredondado para o número de minutos mais próximo, uma vez que o intervalo de atualização é realizado apenas em minutos.

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, é possível que possa 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

A maioria das funcionalidades de suplemento para tipos de dados de entidades ligadas pode ser depurada com 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 implementada num runtime partilhado ou num runtime apenas javaScript (também conhecido como runtime de funções personalizadas.) Se optar por implementar a função num runtime apenas em JavaScript, utilize a depuração de Funções personalizadas numa documentação de orientação de runtime não partilhada .

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 concebido. É também por isso que define o basicType para Error e o basicValue para #VALUE! sempre que insere ou atualiza um valor de célula de entidade ligada. Este é o erro que o Excel utiliza como contingência 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 o utilizador tenha uma funcionalidade imediata, como a capacidade de atualizar os valores das células da entidade ligada.
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

Compartilhar via