Llamar a Excel API de JavaScript desde una función personalizada

Llame a las API de JavaScript de Excel desde una función personalizada cuando su cálculo necesite datos de libro que no se pasan como parámetro. Por ejemplo, una función personalizada puede leer propiedades de documentos, valores o formatos de rango, elementos XML personalizados o el nombre del libro.

Mantener estas llamadas de solo lectura. Una función personalizada que cambia otras celdas o el entorno de Excel puede provocar un rendimiento bajo, tiempos de espera o bucles de cálculo infinitos.

Antes de empezar

El complemento debe usar un tiempo de ejecución compartido antes de que una función personalizada pueda llamar a las API de JavaScript de Excel. Cree un proyecto de funciones personalizadas de Excel con el Kit de herramientas de agentes de Microsoft 365 o configure un complemento existente para usar un entorno de ejecución compartido.

Obtener un valor del libro

Cree un objeto Excel.RequestContext para obtener acceso al libro. Cargue las propiedades que necesita la función, llame y, a context.sync()continuación, devuelva el resultado.

La siguiente función personalizada usa Worksheet.getRange para leer un valor de celda. El address parámetro debe ser una cadena. Por ejemplo, escriba =CONTOSO.GETRANGEVALUE("A1") en una celda para devolver el valor de la celda A1.

/**
 * @customfunction
 * @param {string} address The address of the cell from which to retrieve the value.
 * @returns The value of the cell at the input address.
 **/
async function getRangeValue(address) {
    // Retrieve the context object.
    const context = new Excel.RequestContext();

    // Use the context object to access the cell at the input address.
    const range = context.workbook.worksheets.getActiveWorksheet().getRange(address);
    range.load("values");
    await context.sync();

    // Return the value of the cell at the input address.
    return range.values[0][0];
}

Limitaciones de llamar a las API de JavaScript de Excel a través de una función personalizada

Un complemento de funciones personalizadas puede llamar a las API de JavaScript de Excel, pero debe tener cuidado con las API a las que llama. No llame a Excel API de JavaScript desde una función personalizada que cambie celdas fuera de la celda que ejecuta la función personalizada. Cambiar otras celdas o el entorno de Excel puede provocar un rendimiento bajo, tiempos de espera y bucles infinitos en la aplicación de Excel. Esto significa que las funciones personalizadas no deben realizar ninguna de las siguientes acciones:

  • Insertar, eliminar o dar formato a celdas en la hoja de cálculo.
  • Cambiar el valor de otra celda.
  • Mover, cambiar el nombre, eliminar o agregar hojas a un libro.
  • Agregar nombres a un libro.
  • Establecer propiedades.
  • Cambie cualquiera de las opciones del entorno de Excel, como el modo de cálculo o las vistas de pantalla.

El complemento de funciones personalizadas puede leer información de celdas fuera de la celda que ejecuta la función personalizada, pero no debe realizar operaciones de escritura en otras celdas. En su lugar, realice cambios en otras celdas o en el entorno de Excel desde el contexto de un botón de la cinta o un panel de tareas. Además, los cálculos de funciones personalizadas no deben ejecutarse mientras se realiza un nuevo cálculo de Excel, ya que este escenario crea resultados impredecibles.

Pasos siguientes

Vea también

  • Last updated on