Llamada a las API de JavaScript de Excel desde una función personalizada
Llame a las API de JavaScript de Excel desde las funciones personalizadas para obtener datos de rango y obtener más contexto para los cálculos. Llamar a las API de JavaScript de Excel a través de una función personalizada puede ser útil cuando:
- Una función personalizada debe obtener información de Excel antes del cálculo. Esta información puede incluir propiedades de documento, formatos de intervalo, elementos XML personalizados, un nombre de libro u otra información específica de Excel.
- Una función personalizada establecerá el formato numérico de la celda para los valores devueltos después del cálculo.
Importante
Para llamar a las API de JavaScript de Excel desde la función personalizada, deberá usar un entorno de ejecución compartido. Use el generador de Yeoman para complementos de Office para instalar una función personalizada de Excel mediante un proyecto de tiempo de ejecución compartido o vea Configurar el complemento de Office para usar un entorno de ejecución compartido para obtener más información.
Ejemplo de código
Para llamar a las API de JavaScript de Excel desde una función personalizada, primero necesita un contexto. Use el objeto Excel.RequestContext para obtener un contexto. A continuación, use el contexto para llamar a las API que necesita en el libro.
En el ejemplo de código siguiente se muestra cómo usar Excel.RequestContext para obtener un valor de una celda del libro. En este ejemplo, el address parámetro se pasa al método Worksheet.getRange de la API de JavaScript de Excel y debe escribirse como una cadena. Por ejemplo, la función personalizada especificada en la interfaz de usuario de Excel debe seguir el patrón =CONTOSO.GETRANGEVALUE("A1"), donde "A1" es la dirección de la celda desde la que se va a recuperar el valor.
/**
* @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 las API de JavaScript de Excel desde una función personalizada que cambie las celdas fuera de la celda que ejecuta la función personalizada. Cambiar otras celdas o el entorno de Excel puede dar lugar a un rendimiento deficiente, tiempos de espera y bucles infinitos en la aplicación de Excel. Esto significa que las funciones personalizadas no deben hacer lo siguiente:
- Insertar, eliminar o dar formato a las celdas de la hoja de cálculo.
- Cambie el valor de otra celda.
- Mueva, cambie el nombre, elimine o agregue hojas a un libro.
- Agregue nombres a un libro.
- Establezca las 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 cinta de opciones o un panel de tareas. Además, los cálculos de funciones personalizadas no deben ejecutarse mientras se realiza una actualización de Excel, ya que este escenario crea resultados imprevisibles.