Solucionar problemas de funciones personalizadas

Cuando se desarrollan funciones personalizadas, pueden producirse errores de producto al crear y probar las funciones.

Para resolver problemas, habilite el registro en tiempo de ejecución para capturar errores y consultar mensajes de error de Excel. Asimismo, compruebe si hay errores comunes como dejar promesas sin resolver.

Depuración de funciones personalizadas

Para depurar complementos de funciones personalizadas que usan un tiempo de ejecución compartido, vea Información general sobre la depuración de complementos de Office.

Para depurar complementos de funciones personalizadas que no usan un tiempo de ejecución compartido, consulte Depuración de funciones personalizadas.

Habilitar el registro de tiempo de ejecución

Si va a probar un complemento en Office en Windows, debe habilitar el registro de tiempo de ejecución. El registro de tiempo de ejecución envía instrucciones de console.log a un archivo de registro independiente creado por usted que le servirá de ayuda para descubrir los problemas. Las instrucciones abarcan una variedad de errores, incluidos errores relacionados con el archivo de manifiesto del complemento, las condiciones de tiempo de ejecución o la instalación de las funciones personalizadas. Para obtener más información sobre el registro de tiempo de ejecución, vea Depurar el complemento con el registro en tiempo de ejecución.

Compruebe los mensajes de error de Excel

Excel tiene una serie de mensajes de error integrados que se devuelven a una celda si hay algún error de cálculo. Las funciones personalizadas solo usan los siguientes mensajes de error: #NULL!, #DIV/0!, #VALUE!, #REF!, #NAME?, #NUM!, #N/A y #BUSY!.

Por lo general, estos errores se corresponden con los errores con los que puede que ya esté familiarizado en Excel. Solo hay unas pocas excepciones específicas para las funciones personalizadas que se enumeran aquí:

  • Un error #NAME? normalmente significa que se ha producido un problema al registrar las funciones. Para obtener información adicional, consulte Funciones personalizadas que muestran #NAME? error.
  • Un error #N/A también puede indicar que esa función se registró pero no se pudo ejecutar. Normalmente, es porque falta un comando CustomFunctions.associate.
  • Un error #VALUE! suele indicar un error en el archivo de script de las funciones.
  • Un error #REF! puede indicar que el nombre de la función es igual al nombre de una función en un complemento que ya existe.

Borrar la caché de Office

Office almacena en caché información sobre funciones personalizadas. A veces, al desarrollar y volver a cargar varias veces un complemento con funciones personalizadas, puede que no se muestren los cambios. Puede solucionarlo borrando la caché de Office. Para obtener más información, consulte Borrar la caché de Office.

Borre la caché de funciones personalizadas cuando se ejecute el complemento

Es posible que en ocasiones necesite borrar la memoria caché de funciones personalizadas para un complemento implementado para los usuarios finales, de modo que las actualizaciones de complementos y los cambios en la configuración de funciones personalizadas se incorporen al mismo tiempo. Sin desencadenar un borrado de caché de funciones personalizadas, los cambios en los archivos functions.json y functions.js pueden tardar hasta 24 horas en llegar a los usuarios finales, mientras que los cambios en taskpane.html llegar a los usuarios finales más rápidamente.

Nota:

Una vez activada esta configuración para un documento, tendrá efecto la próxima vez que se abra el documento con el complemento. No se aplica inmediatamente después de llamar a la función.

Para asegurarse de que el complemento borra la caché de funciones personalizadas, agregue el código siguiente al archivo functions.js y, a continuación, llame setForceRefreshOn al método de la Office.onReady llamada u otra lógica de inicialización del complemento.

Importante

Este proceso para borrar la caché de funciones personalizadas solo se admite para los complementos de funciones personalizadas que usan un tiempo de ejecución compartido.

// To enable custom functions cache clearing, add this method to your functions.js 
// file, and then call the `setForceRefreshOn` method in your `Office.onReady` call.
function setForceRefreshOn() {  
    Office.context.document.settings.set(  
        'Office.ForceRefreshCustomFunctionsCache',
        true  
    );  
    Office.context.document.settings.saveAsync();  
}

Sugerencia

Actualizar con frecuencia la caché de funciones personalizadas puede afectar al rendimiento, por lo que borrar la caché setForceRefreshOn de funciones personalizadas solo debe usarse durante el desarrollo del complemento o para resolver errores. Una vez estabilizado un complemento de funciones personalizadas, deje de forzar las actualizaciones de caché.

Para deshabilitar el borrado de caché de funciones personalizadas en el complemento, establezca Office.ForceRefreshCustomFunctionsCache y llame al false método en Office.onReady la llamada. En el ejemplo de código siguiente se muestra un ejemplo con un setForceRefreshOff método.

// To disable custom functions cache clearing, add this method to your functions.js 
// file, and then call the `setForceRefreshOff` method in your `Office.onReady` call.
function setForceRefreshOff() {  
    Office.context.document.settings.set(  
        'Office.ForceRefreshCustomFunctionsCache',
        false  
    );  
    Office.context.document.settings.saveAsync();  
}

Problemas comunes y soluciones

¿Funciones personalizadas que muestran #NAME? de error

Al abrir un libro que usa un complemento de funciones personalizadas, a veces se muestra un #NAME? error en las celdas de función personalizadas en lugar del resultado de la fórmula. Es posible que IntelliSense para funciones personalizadas tampoco aparezca en el libro al crear fórmulas nuevas. La causa probable de este problema es que el complemento de funciones personalizadas no se ha registrado correctamente.

Para resolver el problema, pruebe los siguientes enfoques:

No se puede abrir el complemento desde localhost: Usar una exención de bucle invertido local

Si ve el error "No podemos abrir este complemento desde localhost", deberá habilitar una exención de bucle invertido local. Para obtener información sobre cómo hacerlo, consulte este artículo de soporte técnico de Microsoft.

El registro en tiempo de ejecución informa "TypeError: error de solicitud de red" en Excel para Windows

Si se muestra el error "TypeError: error de solicitud de red" en el registro en tiempo de ejecución mientras realiza llamadas al servidor localhost, deberá habilitar una excepción de bucle invertido local. Para obtener información sobre cómo hacerlo, vea la Opción 2 en este artículo de soporte técnico de Microsoft.

Asegúrese de que se devuelvan las promesas

Cuando Excel está esperando a que se complete una función personalizada, se muestra #BUSY! en la celda. Si el código de la función personalizada devuelve una promesa, pero la promesa no devuelve un resultado, Excel seguirá mostrando #BUSY!. Compruebe las funciones para asegurarse de que las promesas estén devolviendo correctamente los resultados a las celdas.

Asegúrese de que el manifiesto solicite permisos de lectura y escritura

Las funciones personalizadas requieren permisos de lectura y escritura de documentos. Especifique Document.ReadWrite.User en el manifiesto unificado o ReadWriteDocument en el manifiesto de solo complemento. Los permisos de solo lectura pueden hacer que las funciones devuelvan el #BUSY! error.

Error: El servidor de desarrollo se está ejecutando en el puerto 3000

En ocasiones, al ejecutar npm start es posible que vea un error de que el servidor de desarrollo ya se está ejecutando en el puerto 3000 (o el puerto que usa el complemento). Puede detener el servidor de desarrollo ejecutando npm stop o cerrando la ventana Node.js. En algunos casos, el servidor de desarrollo puede tardar unos minutos en dejar de ejecutarse.

No se cargan las funciones: asociar las funciones

En los casos en los que no se haya registrado el JSON y se haya creado su propio metadato de JSON, es posible que vea un error #VALUE! o que reciba una notificación que indica que el complemento no se puede cargar. Normalmente, esto significa que necesita asociar cada función personalizada a id la propiedad especificada en el archivo de metadatos JSON. Esto se hace mediante la CustomFunctions.associate() función. Normalmente, esta llamada a la función se realiza después de cada función o al final del archivo de script. Si la función personalizada no está asociada, no funcionará.

En el siguiente ejemplo se muestra una función de complemento, seguida por el nombre de la función add, que se asocia al id. de JSON correspondienteADD.

/**
 * Add two numbers.
 * @customfunction
 * @param {number} first First number.
 * @param {number} second Second number.
 * @returns {number} The sum of the two numbers.
 */
function add(first, second) {
  return first + second;
}

CustomFunctions.associate("ADD", add);

Para obtener más información sobre este proceso, vea Asociar nombres de función con metadatos JSON.

Problemas conocidos

Se realiza un seguimiento de los problemas conocidos y se notifican en el repositorio de GitHub de Funciones personalizadas de Excel.

Enviar comentarios

Si se encuentra con problemas que no se mencionen aquí, infórmenos. Puede notificar los problemas de dos maneras.

En Excel en Windows o en Mac

Si usa Excel en Windows o en Mac, puede enviar comentarios al equipo de extensibilidad de Office directamente desde Excel. Para ello, seleccione Archivo> Comentarios>Enviar una desaprobación. Al enviar una desaprobación, nos proporcionará los registros necesarios para comprender el problema que ha encontrado.

En Github

Puede notificar los problemas que encuentre mediante la característica "Comentarios acerca del contenido" que hay en la parte inferior de las páginas de documentación, o informando de cada nuevo problema directamente al repositorio de funciones personalizadas.

Siguientes pasos

Obtenga información sobre cómo hacer que las funciones personalizadas sean compatibles con funciones definidas por el usuario XLL.

Vea también

  • Se actualizó por última vez el