Creación de valores de celda de entidad vinculada

Los valores de celda de entidad vinculada integran tipos de datos de orígenes de datos externos y pueden mostrar los datos como una tarjeta de entidad, como valores de entidad normales. Permiten escalar los tipos de datos para representar grandes conjuntos de datos sin descargar todos los datos en el libro. Los dominios de datos Stocks y Geography disponibles a través de la interfaz de usuario de Excel proporcionan valores de celda de entidad vinculada. En este artículo se explica cómo crear su propio proveedor de datos en un complemento de Excel para proporcionar valores personalizados para los usuarios finales.

Los valores de celda de entidad vinculada están vinculados a un origen de datos externo. Proporcionan las siguientes ventajas sobre los valores de entidad normales.

• Los valores de celda de entidad vinculada pueden anidar y los valores de celda de entidad vinculada anidada no se recuperan hasta que se hace referencia a ella; por el usuario o por la hoja de cálculo. Esto ayuda a reducir el tamaño del archivo y mejorar el rendimiento del libro.
• Excel usa una memoria caché para permitir que distintas celdas hagan referencia al mismo valor de celda de entidad vinculada sin problemas. Esto también mejora el rendimiento del libro.

En este artículo se amplía la información descrita en los artículos siguientes. Se recomienda leer los artículos siguientes antes de aprender a crear sus propios valores de celda de entidad vinculada.

• Tipos de datos de Excel: cotizaciones e información geográfica
• Información general sobre los tipos de datos en complementos de Excel
• Tarjeta de valor de entidad de tipos de datos de tipos de datos de la API de JavaScript de Excel

Conceptos básicos

Los valores de celda de entidad vinculada proporcionan al usuario datos vinculados desde un origen de datos externo. El usuario puede verlos como una tarjeta de valor de entidad.

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

Definiciones

Las definiciones siguientes son fundamentales para comprender cómo implementar sus propios valores de celda de entidad vinculada.

• 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.

Cómo proporciona el complemento valores de celda de entidad vinculada

En este diagrama se muestran los pasos que se producen cuando se carga el complemento y, a continuación, se inserta un nuevo valor de celda de entidad vinculada en una celda. En la descripción siguiente se explica lo que ocurre en cada paso del proceso.

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 llamará más adelante a este identificador 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 se crea un nuevo valor de celda de entidad vinculada para el producto Chai. Esto suele ocurrir si 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 .

Nota:

Si Excel necesita varios valores de celda de entidad vinculada, los identificadores de entidad vinculada se pasan como un lote a la función de servicio de carga de entidad vinculada. A continuación, el servicio de carga de entidad vinculada devuelve un resultado por lotes de todos los valores.

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. El proveedor de datos se identifica mediante 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 de este artículo se muestra cómo escribir código TypeScript para implementar un complemento de Excel que sea un proveedor de datos para Contoso. Proporciona dos dominios de datos denominados Products y Categories.

Registro de los dominios de datos

Echemos un vistazo al código para registrar nuevos dominios denominados Productos y categorías. El nombre del proveedor de datos es Contoso. Cuando se carga el complemento, primero registra los dominios de datos con Excel.

Use el tipo Excel.LinkedEntityDataDomainCreateOptions para describir las opciones que desea, incluida la función que se usará como servicio de carga de entidad vinculada. A continuación, agregue el dominio a la colección Workbook.linkedEntityDataDomains . Se recomienda registrar dominios al inicializar el complemento de Office. En el código siguiente se muestra cómo registrar 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 una 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 de código siguiente se muestra cómo insertar un nuevo valor de celda de entidad vinculada en la celda seleccionada. Se puede llamar a este código desde un botón de comando de la cinta de opciones o desde un botón en el panel de tareas. Notas sobre el código siguiente:

• 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 lo pasará a la función de servicio de carga de entidad vinculada para que pueda mantener la referencia cultural original cuando el libro se abra 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();
    });
}

Nota:

No use signos de exclamación en los entityID valores o domainId .

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. Esto 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, el usuario puede actualizarlo manualmente en cualquier momento, por ejemplo, seleccionando Actualizar todo en la pestaña Datos . Hay tres modos de actualización que puede especificar para el dominio de datos.

• manual- Los datos solo se actualizan cuando el usuario decide actualizar. Este es el modo predeterminado. El usuario siempre puede realizar la actualización manual, incluso cuando el modo de actualización está establecido en onLoad o periodic.
• onLoad- Los datos se actualizan cuando se registra el dominio de datos (normalmente cuando se carga el complemento). Después, el usuario solo actualiza los datos manualmente. Si desea actualizar los datos cuando se abre 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- Los datos se actualizan cuando se registra el dominio de datos (normalmente cuando se carga el complemento). Después, los datos se actualizan continuamente después de un intervalo de tiempo especificado. Por ejemplo, podría especificar que el dominio de datos se actualice cada 300 segundos (que es el valor mínimo). El número de segundos siempre se redondea al número más cercano de minutos, ya que el intervalo de actualización solo se realiza en minutos.

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, es posible que se produzca 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

La mayoría de la funcionalidad de complemento para los tipos de datos de entidad vinculada se puede depurar mediante 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 se puede implementar en un entorno de ejecución compartido o en un entorno de ejecución solo de JavaScript (también se conoce como tiempo de ejecución de funciones personalizado). Si decide implementar la función en un entorno de ejecución de solo JavaScript, use la depuración funciones personalizadas en una guía de tiempo de ejecución no compartida .

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 es el comportamiento diseñado. Esta es también la razón por la que establece en basicTypeError y en basicValue#VALUE! cada vez que inserta o actualiza un valor de celda de entidad vinculada. Este es el error que Excel usa como reserva 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 código Office.OnReady de inicialización para que el usuario tenga funcionalidad inmediata, como la capacidad de actualizar los valores de celda de entidad vinculada.
• 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