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. Además, los valores de celda de entidad vinculada anidada no se recuperan a menos que el usuario los solicite (como la visualización de la tarjeta de entidad). Y los valores de celda de entidad anidada no se guardan con la hoja de cálculo a menos que se haga referencia a ellos desde la hoja de cálculo (por ejemplo, una fórmula). Esto reduce el tamaño del archivo y mejora el rendimiento.

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. El complemento proporciona 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 el ejemplo de código siguiente se muestra cómo crear una función que controla las solicitudes de datos de Excel para los dominios de datos Products y Categories . Notas sobre el código siguiente:

• Usa funciones auxiliares para crear los valores de celda de entidad vinculada. Ese código se muestra más adelante.
• Si se produce un error, se produce un CustomFunctions.ErrorCode.notAvailable error. Este error se muestra #CONNECT! en la celda que ve el usuario.

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

En el ejemplo de código siguiente se muestra la función auxiliar para crear un valor de celda de entidad vinculada de producto. El código contosoLoadService anterior llama a esta función para crear una entidad vinculada para un identificador de producto específico. Notas sobre el código siguiente:

• 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. El código contosoLoadService anterior llama 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. El código contosoLoadService anterior llama 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;
}

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

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 el notAvailableError error. 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