Creación de tipos de datos de entidad vinculada en complementos de Excel

Use valores de celda de entidad vinculada cuando el complemento de Excel necesite mostrar datos externos sin almacenar el conjunto de datos completo en el libro. Por ejemplo, puede mostrar un producto, cliente o proveedor en una celda, abrir una tarjeta enriquecida para obtener detalles y cargar datos anidados solo cuando Excel lo necesite.

Excel usa el mismo patrón para los tipos de datos vinculados integrados, como Stocks y Geography. En este artículo se muestra cómo crear su propio proveedor de datos en un complemento de Excel.

En este artículo, aprenderá a:

• Registrar dominios de datos de entidad vinculada.
• Inserte valores de celda de entidad vinculada desde un comando o una función personalizada.
• Implemente una función de servicio de carga de entidad vinculada.
• Configure la actualización y el control de errores.

Antes de empezar, revise estos artículos relacionados:

• Información general sobre los tipos de datos en complementos de Excel
• Uso de tipos de datos en complementos de Excel
• Uso de tarjetas con tipos de datos de valor de celda
• Agregar propiedades a valores de celda básicos de Excel

Qué hacen los valores de celda de entidad vinculada

Los valores de celda de entidad vinculada conectan las celdas del libro a un origen de datos externo y muestran el resultado como una tarjeta de entidad.

Al igual que los valores de entidad normales, puede hacer referencia a los valores de celda de entidad vinculada en fórmulas.

En comparación con los valores de entidad normales, los valores de celda de entidad vinculada ofrecen estas ventajas.

• Los valores de celda de entidad vinculada anidada no se recuperan hasta que el usuario o la hoja de cálculo hacen referencia a ellos. Esto ayuda a reducir el tamaño del archivo y mejorar el rendimiento del libro.
• Excel almacena en caché los valores de celda de entidad vinculada para que varias celdas puedan hacer referencia al mismo valor de forma eficaz.

Términos clave

Use los siguientes términos a lo largo de este artículo.

• Dominio de datos de entidad vinculada : un dominio de datos de entidad vinculado describe la categoría general a la que pertenece una entidad. Algunos ejemplos son empleados, organizaciones o automóviles.
• Valor de celda de entidad vinculada : instancia creada a partir de un dominio de datos. Un ejemplo es un valor de empleado para alguien llamado Joe. Se puede mostrar como una tarjeta de valor de entidad.
• Proveedor de datos : Excel reconoce el proveedor de datos como origen de datos para uno o varios dominios de datos de entidad vinculada registrados.
• Función de servicio de carga de entidad vinculada : cada dominio de datos de entidad vinculada define una función de servicio de carga para que actúe como origen de datos para ese dominio. La función de servicio de carga de entidad vinculada controla las solicitudes de Excel para obtener valores de celda de entidad vinculada para el libro. Se implementa como una función personalizada de TypeScript o JavaScript.

Funcionamiento del flujo de entidad vinculada

En este diagrama se muestra lo que sucede después de que el complemento se cargue e inserte un valor de celda de entidad vinculada en una celda.

1. Excel carga el complemento y el complemento registra todos los dominios de datos de entidad vinculada que admite. Cada registro incluye el identificador de una función de servicio de carga de entidad vinculada. Excel llama a este identificador más adelante para solicitar valores de propiedad para el valor de celda de entidad vinculada desde el dominio de datos de entidad vinculada. En este ejemplo, se registra un dominio de datos denominado Products .
2. Excel realiza un seguimiento de cada dominio de datos de entidad vinculada registrada en una colección de dominios de datos de entidad vinculada. Esto permite a Excel llamar a la función de servicio de carga de entidad vinculada cuando se necesitan datos para un valor de celda de entidad vinculada.
3. El complemento inserta un nuevo valor de celda de entidad vinculada en la hoja de cálculo. En este ejemplo, creará un nuevo valor de celda de entidad vinculada para el producto Chai. Este paso suele producirse cuando el usuario elige un botón en el complemento que da como resultado la creación de uno o más valores de celda de entidad vinculada. Al crear nuevos valores de celda de entidad vinculada, solo contienen una cadena de texto inicial que se muestra en la celda. Excel llama a la función de servicio de carga de entidad vinculada para obtener los valores de propiedad restantes. El complemento también puede crear valores de celda de entidad vinculada a partir de funciones personalizadas.
4. Excel llama a la función de servicio de carga de entidad vinculada que registró en el paso 1. Esto ocurre cada vez que se crea un nuevo valor de celda de entidad vinculada, o si se produce una actualización de datos. Excel llama a la función de servicio de carga de entidad vinculada para obtener todos los valores de propiedad.
5. La función de servicio de carga de entidad vinculada devuelve un valor actualizado de celda de entidad vinculada (Excel.LinkedEntityCellValue) para el identificador de entidad vinculado (Excel.LinkedEntityId) solicitado por Excel. Normalmente, la función de servicio de carga de entidad vinculada consulta un origen de datos externo para obtener los valores y crear el valor de celda de entidad vinculada. En este ejemplo, se devuelven los valores de id. de producto, categoría, cantidad y precio .

En las secciones siguientes se proporcionan detalles adicionales sobre los términos definidos anteriormente en este artículo.

Proveedor de datos

El complemento es el proveedor de datos y Excel reconoce como origen de datos para uno o varios dominios de datos registrados. El complemento expone una o varias funciones del proveedor de datos que devuelven datos para los valores de celda de entidad vinculada. En Excel.LinkedEntityDataDomainCreateOptions, establezca dataProvider en una cadena de texto como Contoso o el nombre del complemento. El nombre debe ser único dentro del complemento.

Dominios de datos de entidad vinculada

El proveedor de datos (el complemento) registra uno o varios dominios de datos. Un dominio de datos describe una entidad en Excel. Por ejemplo, un proveedor de datos puede proporcionar los dominios de datos products y categories . Los dominios deben registrarse con Excel para que puedan trabajar con esos dominios para recuperar y mostrar valores de celda de entidad vinculada y realizar cálculos.

Un dominio de datos describe a Excel los siguientes atributos:

• Nombre del proveedor de datos al que está asociado.
• Un identificador de dominio para identificarlo de forma única, como los productos.
• Nombre para mostrar para el usuario, como Products.
• Función de servicio de carga de entidad vinculada a la que llamar cuando Excel necesita un valor de celda de entidad vinculada.
• Un modo de actualización y un intervalo especificados que describen la frecuencia con la que se actualiza.

Un ejemplo de un dominio de datos de entidad vinculada es el dominio de datos Geography en Excel que proporciona valores de celda de entidad vinculada para las ciudades.

Valor de celda de entidad vinculada

Un valor de celda de entidad vinculada es una instancia creada a partir de un dominio de datos. Un ejemplo es un valor para Seattle, del dominio de datos Geography. Muestra una tarjeta de valor de entidad como valores normales de celda de entidad.

Dado que los valores de celda de entidad vinculada están vinculados al dominio de datos, se pueden actualizar. Al implementar valores de celda de entidad vinculada anidada, tenga en cuenta los siguientes comportamientos que reducen el tamaño del archivo para mejorar el rendimiento.

• Los valores de celda de entidad vinculada anidada no se recuperan a menos que el usuario los solicite, como al ver la tarjeta de entidad.
• Los valores de celda de entidad vinculada anidada no se guardan con la hoja de cálculo a menos que la hoja de cálculo haga referencia a ellos, como una fórmula.

Función de servicio de carga de entidad vinculada

Cada dominio de datos requiere una función a la que Excel puede llamar cuando necesita valores de celda de entidad vinculada. Implemente el servicio como una función de JavaScript o TypeScript etiquetada con @linkedEntityLoadService. Se recomienda crear solo una función de servicio de carga para obtener el mejor rendimiento. Excel envía todas las solicitudes de valores de celda de entidad vinculada como lote a la función de servicio de carga.

Creación de un proveedor de datos con dominios de datos

En las secciones siguientes se muestra cómo escribir código TypeScript para un complemento de Excel que actúa como proveedor de datos para Contoso. En este ejemplo, el complemento proporciona tres dominios de datos: Productos, Categorías y Proveedores.

Registro de los dominios de datos

Para empezar, registre cada dominio de datos compatible con el complemento. En este ejemplo, el nombre del proveedor de datos es Contoso y los dominios son Productos, Categorías y Proveedores.

Use Excel.LinkedEntityDataDomainCreateOptions para definir cada dominio, incluida la función de servicio de carga de entidad vinculada a la que Excel debe llamar. A continuación, agregue cada dominio a la colección Workbook.linkedEntityDataDomains . Registre dominios al inicializar el complemento de Office.

El código siguiente registra los dominios de datos Productos, Categorías y Proveedores .

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

Insertar un valor de celda de entidad vinculada

Hay dos maneras de insertar un valor de celda de entidad vinculada en una celda de hoja de cálculo.

• Cree un botón de comando en la cinta de opciones o un botón en el panel de tareas. Cuando el usuario selecciona el botón, el código inserta un valor de celda de entidad vinculada.
• Cree una función personalizada que devuelva un valor de celda de entidad vinculada.

En el ejemplo siguiente se inserta un nuevo valor de celda de entidad vinculada en la celda seleccionada. Puede llamar a este código desde un comando de cinta de opciones o desde un botón del panel de tareas.

Tenga en cuenta los siguientes requisitos:

• Debe especificar un serviceId valor de para los valores de celda de 268436224 entidad vinculada que devuelva. Esto informa a Excel de que el valor de la celda de entidad vinculada está asociado a un complemento de Excel.
• Debe especificar un objeto culture. Excel pasa este valor a la función de servicio de carga de entidad vinculada para que pueda mantener la referencia cultural original cuando el libro se abre en una referencia cultural diferente.
• La text propiedad se muestra al usuario en la celda mientras se actualiza el valor de datos de entidad vinculada. Esto impide que el usuario vea una celda en blanco mientras se completa la actualización.

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

En el ejemplo de código siguiente se muestra cómo insertar un valor de celda de entidad vinculada mediante una función personalizada. Un usuario podría obtener un valor de celda de entidad vinculada escribiendo =CONTOSO.GETPRODUCTBYID("productid") en cualquier celda. Las notas del ejemplo de código anterior también se aplican 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;
}

Implementación de la función de servicio de carga de entidad vinculada

El complemento debe proporcionar una función de servicio de carga de entidad vinculada para controlar las solicitudes de Excel cuando se necesitan valores de propiedad para cualquier valor de celda de entidad vinculada. La función se identifica con la @linkedEntityLoadService etiqueta JSDoc.

En los ejemplos de código siguientes se muestra cómo:

• Cree funciones auxiliares usadas por la función de servicio de carga para generar LinkedEntityCellValue objetos.
• Cree una función para controlar las solicitudes de datos de Excel para los dominios de datos Productos, Categorías y Proveedores .

Creación de funciones auxiliares

En el ejemplo de código siguiente se muestra la función auxiliar para crear un valor de celda de entidad vinculada de producto. La función de servicio de carga llama contosoLoadService a esta función para crear una entidad vinculada para un identificador de producto específico. Tenga en cuenta lo siguiente sobre el código.

• Usa la misma configuración que el ejemplo anterior insertProduct para las typepropiedades , idy text .
• Incluye propiedades adicionales específicas del dominio de datos Products , como Product Name y Unit Price.
• Crea una entidad vinculada anidada diferida para la categoría del producto. Las propiedades de la categoría no se solicitan hasta que se necesitan.

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

En el ejemplo de código siguiente se muestra la función auxiliar para crear un valor de celda de entidad vinculada de categoría. La función de servicio de carga llama contosoLoadService a esta función para crear una entidad vinculada para un identificador de categoría 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;
}

En el ejemplo de código siguiente se muestra la función auxiliar para crear un valor de celda de entidad vinculada de proveedor. La función de servicio de carga llama contosoLoadService a esta función para crear una entidad vinculada para un identificador de proveedor 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;
}

Implementación de la función de servicio de carga mediante las funciones auxiliares

El código siguiente muestra una función de servicio de carga de entidad vinculada que llama a las funciones auxiliares para crear los valores de celda de entidad vinculada. Tenga en cuenta lo siguiente sobre el código.

• La función de servicio de carga analiza el objeto entrante LinkedEntityLoadServiceRequest para extraer el identificador de dominio y los identificadores de entidad. Estos identificadores se usan para identificar a qué dominio de datos pertenece una entidad, de modo que se pueda llamar a las funciones auxiliares adecuadas para crear un valor de celda de entidad vinculada.
• Las funciones auxiliares crean los objetos completos LinkedEntityCellValue con todas las propiedades rellenadas.
• La función de servicio de carga devuelve un LinkedEntityLoadServiceResult objeto que contiene los valores de celda de entidad vinculada en el mismo orden en que se solicitaron.

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

El ejemplo de código siguiente contiene datos de ejemplo que puede usar con los ejemplos 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"
    }];

Opciones de actualización de datos

Al registrar un dominio de datos, los usuarios pueden actualizarlo manualmente en cualquier momento, por ejemplo, seleccionandoActualizar todos los datos>. También puede configurar uno o varios de los siguientes modos de actualización.

• manual: actualiza los datos solo cuando el usuario decide actualizar. Este es el modo predeterminado. La actualización manual siempre está disponible, incluso cuando el modo de actualización está establecido en onLoad o periodic.
• onLoad: actualiza los datos cuando se registra el dominio de datos, lo que suele ocurrir cuando se carga el complemento. Después, los usuarios actualizan los datos manualmente. Si desea actualizar los datos cuando se abra el libro, configure el complemento para que se cargue en el documento abierto. Para obtener más información, vea Ejecutar código en el complemento de Office cuando se abra el documento.
• periodic: actualiza los datos cuando el dominio de datos está registrado y, a continuación, los actualiza de nuevo en un intervalo especificado. Por ejemplo, puede actualizar cada 300 segundos, que es el valor mínimo. Excel redondea el intervalo hasta el minuto más cercano porque solo se actualiza en incrementos de minutos enteros.

En el ejemplo de código siguiente se muestra cómo configurar un dominio de datos para que se actualice al cargar y, a continuación, continuar con la actualización 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
    ]
};

También puede solicitar mediante programación una actualización en un dominio de datos de entidad vinculada mediante cualquiera de los métodos siguientes.

• LinkedEntityDataDomain.refresh() : actualiza todos los LinkedEntityCellValue objetos del dominio de datos de entidad vinculada.
• LinkedEntityDataDomainCollection.refreshAll() : actualiza todos los LinkedEntityCellValue objetos de todos los dominios de datos de entidad vinculados de la colección.

Los métodos de actualización solicitan una actualización que se produce de forma asincrónica. Para determinar los resultados de la actualización, escuche el onRefreshCompleted evento. En el ejemplo de código siguiente se muestra un ejemplo de escucha para el 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;
}

Consulta de valores de celda de entidad vinculada

Si tiene identificadores de entidad y dominio de una entidad vinculada, puede cargarlo sin agregarlo a un libro llamando al loadLinkedEntityCellValue método . El método es asincrónico y devuelve los resultados a través del evento onLinkedEntityCellValueLoaded . Debe registrar un controlador de eventos para este evento antes de llamar a loadLinkedEntityCellValue. El objeto LinkedEntityCellValueLoadedEventArgs pasado al controlador de eventos contiene la información de error y cargada LinkedEntityCellValue .

En el ejemplo de código siguiente se muestra cómo registrar e implementar un controlador de eventos y llamar a 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.
  });
}

Control de errores con el servicio de carga de entidades vinculadas

Cuando Excel llama al complemento para obtener datos de un valor de celda de entidad vinculada, se puede producir un error. Si Excel no puede conectarse al complemento en absoluto, como cuando el complemento no se carga, Excel muestra el #CONNECT! error al usuario.

Si la función de servicio de carga de entidad vinculada encuentra un error, debería producir un CustomFunctions.Error con CustomFunctions.ErrorCode.notAvailable. Esto hace que Excel se muestre #CONNECT! al usuario.

En el código siguiente se muestra cómo controlar un error en una función de servicio de carga de entidad 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;
    }
}

Depuración del servicio de carga de entidades vinculadas

Puede depurar la mayor parte de la funcionalidad de complemento de entidad vinculada siguiendo las instrucciones de Información general sobre la depuración de complementos de Office. Sin embargo, la función de servicio de carga de entidad vinculada puede ejecutarse en un entorno de ejecución compartido o en un entorno de ejecución solo de JavaScript, también conocido como tiempo de ejecución de funciones personalizado. Si implementa la función en un entorno de ejecución de solo JavaScript, use la depuración de funciones personalizadas en un entorno de ejecución no compartido.

La función de servicio de carga de entidad vinculada usa la arquitectura de funciones personalizadas, independientemente del entorno de ejecución que use. Sin embargo, hay diferencias significativas con respecto a las funciones personalizadas normales.

Las funciones del servicio de carga de entidades vinculadas tienen las siguientes diferencias con respecto a las funciones personalizadas:

• No parecen ser usuarios finales para su uso en fórmulas.
• No admiten las etiquetas @streaming JSDoc ni @volatile. El usuario verá un error #CALC! si se usan estas etiquetas.

Las funciones del servicio de carga de entidades vinculadas tienen las siguientes similitudes con las funciones personalizadas:

• Usan la nomenclatura y localización de funciones personalizadas.
• Usan el mismo enfoque de control de errores.

Comportamiento en Excel 2019 y versiones anteriores

Si alguien abre una hoja de cálculo con valores de celda de entidad vinculada en una versión anterior de Excel que no admite valores de celda de entidad vinculada, Excel muestra los valores de celda como errores. Este comportamiento es una característica del diseño de la aplicación. Este comportamiento también es el motivo por el que establece en basicTypeError y en basicValue#VALUE! cada vez que inserta o actualiza un valor de celda de entidad vinculada. Este error es la reserva que Excel usa en versiones anteriores.

Procedimientos recomendados

• No use signos de exclamación en los entityID valores o domainId .
• Registre dominios de datos de entidad vinculada en el Office.onReady código de inicialización para que los usuarios puedan actualizar los valores de celda de entidad vinculada tan pronto como se cargue el complemento.
• Después de publicar el complemento, no cambie los identificadores de dominio de datos de entidad vinculada. Los identificadores coherentes en los mismos objetos lógicos ayudan con el rendimiento.
• Proporcione siempre la text propiedad al crear un nuevo valor de celda de entidad vinculada. Este valor se muestra mientras Excel llama a la función del proveedor de datos para obtener los valores de propiedad restantes. De lo contrario, el usuario ve una celda en blanco hasta que se recuperan los datos.

Vea también

• Información general sobre los tipos de datos en complementos de Excel
• Uso de tipos de datos en complementos de Excel
• Uso de tarjetas con tipos de datos de valor de celda
• Agregar propiedades a valores de celda básicos de Excel
• Funciones personalizadas y tipos de datos