Crear funciones personalizadas en Excel

Las funciones personalizadas permiten a los desarrolladores añadir a Excel funciones nuevas definiéndolas en JavaScript como parte de un complemento. Los usuarios de Excel pueden acceder a las funciones personalizadas como lo harían a las funciones nativas de Excel, como SUM().

Nota:

La función personalizada es un término general que se puede intercambiar con la función definida por el usuario. Ambos términos se aplican a los complementos VBA, COM y Office.js. La documentación de los complementos de Office usa el término función personalizada al hacer referencia a funciones personalizadas que usan las API de JavaScript de Office.

La siguiente imagen animada muestra el libro llamando a una función que ha creado con JavaScript o Typescript. En este ejemplo, la función personalizada =MYFUNCTION.SPHEREVOLUME calcula el volumen de una esfera.

Imagen animada en la que se muestra a un usuario final insertando la función personalizada MYFUNCTION.SPHEREVOLUME en una celda de una hoja de cálculo de Excel.

El código siguiente define la función personalizada =MYFUNCTION.SPHEREVOLUME.

/**
 * Returns the volume of a sphere.
 * @customfunction
 * @param {number} radius
 */
function sphereVolume(radius) {
  return Math.pow(radius, 3) * 4 * Math.PI / 3;
}

Cómo se define una función personalizada en código

Si usa el generador Yeoman para complementos de Office para crear un proyecto de complementos de funciones personalizadas de Excel, crea archivos que controlan las funciones y el panel de tareas. Nos concentraremos en los archivos que son importantes para las funciones personalizadas:

Archivo Formato de archivos Descripción
./src/functions/functions.js
o
./src/functions/functions.ts		 JavaScript
o
TypeScript		 Contiene el código que define las funciones personalizadas.
./src/functions/functions.html HTML Proporciona una referencia <script> al archivo de JavaScript que define las funciones personalizadas.
./manifest.xml o ./manifest.json XML o JSON Especifica la ubicación de varios archivos que la función personalizada usa, como las funciones personalizadas de archivos JavaScript, JSON y HTML. Asimismo, se enumeran las ubicaciones de los archivos de panel de tareas, los archivos de comandos y se especifica el tiempo de ejecución que deberían usar las funciones personalizadas. El generador de Yeoman para complementos de Office crea un proyecto con un manifiesto XML.

Sugerencia

El generador de Yeoman para complementos de Office ofrece varios proyectos de funciones personalizadas de Excel . Recomendamos seleccionar el tipo de proyecto Funciones personalizadas de Excel mediante un entorno de ejecución compartido y el tipo de script JavaScript.

Archivo de script

El archivo de script (./src/functions/functions.js o ./src/functions/functions.ts) contiene el código que define las funciones personalizadas y los comentarios que definen la función.

El código siguiente define la función personalizada add. Los comentarios de código se usan para generar un archivo de metadatos JSON que describe la función personalizada en Excel. El comentario requerido @customfunction se declara en primer lugar para indicar que se trata de una función personalizada. A continuación, se declaran dos parámetros, first y second, seguidos de sus propiedades description. Por último, se proporciona una descripción returns. Para más información sobre qué comentarios son necesarios para la función personalizada, consulte Generar automáticamente metadatos JSON para funciones personalizadas.

/**
 * Adds two numbers.
 * @customfunction 
 * @param first First number.
 * @param second Second number.
 * @returns The sum of the two numbers.
 */

function add(first, second){
  return first + second;
}

Sugerencia

En Excel en la Web, las descripciones de función personalizadas y las descripciones de parámetros se muestran en línea. Esto proporciona a los usuarios información adicional al escribir funciones personalizadas. Obtenga información sobre cómo configurar las descripciones en línea explorando cualquiera de las funciones personalizadas Ejemplos de Script Lab en Excel en la Web. Vea la siguiente captura de pantalla para ver un ejemplo.

Una función personalizada con descripciones insertadas que se muestra en Excel en la Web.

Archivo de manifiesto

El archivo de manifiesto de un complemento que define las funciones personalizadas configura el espacio de nombres, especifica las ubicaciones de los archivos y define el tiempo de ejecución. Seleccione la pestaña para el tipo de manifiesto que está usando.

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

El manifiesto unificado de un complemento que define funciones personalizadas (./manifest.json en el proyecto) hace varias cosas.

  • Define el espacio de nombres para las funciones personalizadas mediante el customFunctions.namespace objeto. Un espacio de nombres se antepone a las funciones personalizadas para ayudar a los clientes a identificar las funciones como parte de su complemento.
  • Usa la customFunctions extensión para especificar metadatos sobre funciones personalizadas, incluida la ubicación del archivo de metadatos JSON a través de la metadataUrl propiedad.
  • Configura el tiempo de ejecución para funciones personalizadas mediante la runtimes matriz con una actions.type propiedad establecida en "executeFunction".

Para ver un manifiesto funcional completo de un complemento de ejemplo, vea el manifiesto en uno de nuestros repositorios de GitHub de muestras de complementos de Office.

Sugerencia

Si va a probar el complemento en varios entornos (por ejemplo, en desarrollo, ensayo, demostración, etc.), se recomienda mantener un archivo de manifiesto diferente para cada entorno. En cada archivo de manifiesto, puede:

  • Especificar las direcciones URL que corresponden al entorno.

  • Personalice los valores de metadatos para que los usuarios finales puedan identificar el entorno correspondiente de un complemento transferido. Por ejemplo:

    • En el manifiesto unificado para Microsoft 365, personalice la "name" propiedad del complemento y las "label" propiedades de varios controles de la interfaz de usuario para indicar el entorno.
    • En el manifiesto de solo complemento, personalice el elemento y las DisplayName etiquetas dentro del Resources elemento para indicar el entorno.

  • Personalizar las funciones personalizadas namespace para indicar el entorno, si el complemento define funciones personalizadas.

Siguiendo esta guía simplificará el proceso de prueba y evitará problemas que, de lo contrario, se producirían cuando un complemento de instalación de prueba se transfiere simultáneamente a múltiples entornos.

Coautoría

Excel en la Web y en Windows conectados a una suscripción a Microsoft 365 permiten a los usuarios finales trabajar en coautoría en Excel. Si el libro de un usuario final usa una función personalizada, se le pedirá al compañero de coautoría de ese usuario final que cargue el complemento de funciones personalizadas correspondiente. Una vez ambos usuarios hayan cargado el complemento, la función personalizada comparte los resultados mediante la coautoría.

Para obtener más información sobre la coautoría, vea Información sobre la coautoría en Excel.

Plataformas compatibles

Las funciones personalizadas de Excel son compatibles con la mayoría de las aplicaciones cliente de Office. Las funciones personalizadas de Excel no se admiten actualmente en Office en iPad ni en versiones perpetuas con licencia por volumen de Office 2021 o versiones anteriores en Windows. Para obtener más información, consulte Conjuntos de requisitos de funciones personalizadas.

Siguientes pasos

¿Quiere probar las funciones personalizadas? Consulte el sencillo inicio rápido de funciones personalizadas o el tutorial de funciones personalizadas más detallado si aún no lo ha hecho.

Otra forma sencilla para probar las funciones personalizadas es usar Script Lab, un complemento que le permite experimentar con funciones personalizadas en Excel. Puede probar a crear su propia función personalizada o experimentar con los ejemplos proporcionados.

Consulte también

  • Se actualizó por última vez el