Crear funciones personalizadas en Excel

  • Artículo

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:

Función personalizada es un término general que es intercambiable 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 complementos de Office usa el término función personalizada al hacer referencia a funciones personalizadas que usan las API de JavaScript de Office.

Importante

Tenga en cuenta que las funciones personalizadas están disponibles en Excel en las siguientes plataformas.

  • Office en Windows
    • Suscripción a Microsoft 365
    • Retail perpetual Office 2016 y versiones posteriores
  • Office en Mac
  • Office en la Web

Las funciones personalizadas de Excel no se admiten actualmente en lo siguiente:

  • Office en iPad
  • versiones perpetuas con licencia por volumen de Office 2019 o versiones anteriores

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 XML 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.

Sugerencia

El generador de Yeoman para complementos de Office ofrece varios proyectos de Excel Custom Functions . Se recomienda seleccionar el tipo de proyecto Excel Custom Functions 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;
}

Archivo de manifiesto

El archivo de manifiesto XML para un complemento que define funciones personalizadas (./manifest.XML en el proyecto que crea el generador Yeoman para complementos de Office) realiza varias cosas.

  • Define el espacio de nombres de las funciones personalizadas. 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 <elementos ExtensionPoint> y <Resources> que son únicos para un manifiesto de funciones personalizadas. Estos elementos contienen la información sobre las ubicaciones de los archivos JavaScript, JSON y HTML.
  • Especifica el tiempo de ejecución que se usará para la función personalizada. Se recomienda usar siempre un motor en tiempo de ejecución compartido, a menos que tenga una necesidad específica para otro motor en tiempo de ejecución, ya que un tiempo de ejecución compartido permite el uso compartido de datos entre funciones y el panel de tareas.

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

Sugerencia

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

  • Especificar las direcciones URL que corresponden al entorno.
  • Personalizar valores de metadatos como DisplayName y etiquetas dentro de Resources para indicar el entorno, de modo que los usuarios finales puedan identificar el entorno correspondiente a un complemento de instalación de prueba.
  • 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.

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