Funciones personalizadas sincrónicas (versión preliminar)

Nota:

Las funciones personalizadas sincrónicas están disponibles en versión preliminar pública y están sujetas a cambios en función de los comentarios. No use funciones personalizadas sincrónicas en un complemento de producción.

Para usar esta característica, debe usar la versión preliminar de la biblioteca de API JavaScript de Office de la red de entrega de contenido (CDN)Office.js. El tipo de archivo de definición para la compilación TypeScript e IntelliSense se encuentra en la CDN y DefinitelyTyped. Puede instalar estos tipos con npm install --save-dev @types/office-js-preview.

Las funciones personalizadas sincrónicas permiten que los procesos de evaluación y formato condicional se ejecuten en Excel simultáneamente con la función personalizada. Habilite la compatibilidad sincrónica cuando la función personalizada necesite ejecutarse junto con cualquiera de los procesos de Excel enumerados en este artículo. Las funciones personalizadas que no admiten operaciones sincrónicas devuelven un error como #CALC! o #VALUE! cuando se ejecutan al mismo tiempo que estos procesos de Excel.

Advertencia

Las funciones personalizadas sincrónicas no admiten operaciones de escritura con las API de JavaScript de Office, como el uso Range.values para establecer un valor de celda. Llamar a una operación de escritura en una función personalizada sincrónica puede hacer que Excel se bloquee.

Procesos de Excel admitidos por funciones personalizadas sincrónicas

Las siguientes acciones y procesos funcionan con funciones personalizadas sincrónicas.

Acciones de evaluación admitidas

  • Seleccionar fórmulas y, a continuación, Evaluar fórmula en Excel.
  • Seleccionar Fórmulas y, a continuación, Insertar función en Excel.
  • En modo de edición de celdas, seleccionando parte de una fórmula y usando F9 para ver resultados de cálculos parciales.
  • El Application.Calculate método en VBA.

Acciones de formato condicional admitidas

La siguiente lista se aplica a las acciones de formato condicional desencadenadas por las API de JavaScript y de interfaz de usuario de Excel.

  • Cree una nueva regla
  • Editar reglas.
  • Eliminar reglas.
  • Reordenar reglas.
  • Cambie el rango de "Se aplica a".
  • Activar o desactivar "Detener si es verdadero".
  • Borrar todas las reglas.
  • Cortar y pegar celdas que contienen formato condicional.
  • Copie y pegue celdas que contengan formato condicional.

Nota:

Cuando una función personalizada sincrónica tarda una cantidad significativa de tiempo en completarse, Excel puede bloquear temporalmente la interfaz de usuario mientras espera el resultado. Para evitar interrupciones prolongadas, los usuarios pueden cancelar la ejecución de la función en cualquier momento mediante la tecla Esc o seleccionando cualquier lugar fuera de la celda o el cuadro de diálogo.

Habilitar la compatibilidad sincrónica en el complemento

Para admitir escenarios sincrónicos en el complemento, siga estos pasos.

Importante

Las funciones personalizadas sincrónicas no pueden ser funciones volátiles ni de streaming. Si usa la @supportSync etiqueta con etiquetas o@streaming, Excel ignorará la compatibilidad sincrónica@volatile. La compatibilidad volátil o de streaming tiene prioridad.

Ejemplo de código

En el ejemplo de código siguiente se muestra cómo crear una función personalizada sincrónica.

/** 
 * A synchronous custom function that takes a cell address and returns the value of that cell.
 * @customfunction
 * @supportSync
 * @param {string} address The address of the cell from which to retrieve the value.
 * @param {CustomFunctions.Invocation} invocation Invocation object.
 * @returns The value of the cell at the input address.
 */ 
export async function getCellValue(address, invocation) {
  const context = new Excel.RequestContext();
  context.setInvocation(invocation); // The `invocation` object must be passed in the `setInvocation` method for synchronous functions.

  const range = context.workbook.worksheets.getActiveWorksheet().getRange(address);
  range.load("values");

  await context.sync(); 
  return range.values[0][0];
}

Sugerencia

Para explorar las funciones personalizadas sincrónicas en un complemento completo, consulte Creación de funciones personalizadas sincrónicas en Excel (versión preliminar) en nuestro repositorio de ejemplos de código de complementos de Office.

Vea también

  • Last updated on