Generar automáticamente metadatos JSON de funciones personalizadas

Cuando se escribe una función personalizada de Excel en JavaScript o TypeScript, se usan etiquetas JSDoc para proporcionar información adicional sobre la función personalizada. Proporcionamos un complemento Webpack que usa estas etiquetas JSDoc para crear automáticamente el archivo de metadatos JSON en tiempo de compilación. El uso del complemento le ahorra el esfuerzo de editar manualmente el archivo de metadatos JSON.

Importante

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

• Office en la web
• Office en Windows
  • Suscripción a Microsoft 365
  • Retail perpetual Office 2016 y versiones posteriores
  • Licencia por volumen perpetua de Office 2021 y versiones posteriores
• Office en Mac

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 en Windows

CustomFunctionsMetadataPlugin

El complemento es CustomFunctionsMetadataPlugin. Para instalarlo y configurarlo, siga estos pasos.

Nota:

• La herramienta solo se puede usar en un proyecto basado en NodeJS.
• En estas instrucciones se supone que el proyecto usa Webpack y que lo tiene instalado y configurado.
• Si el proyecto de complemento de función personalizada se crea con el generador de Yeoman para complementos de Office, Webpack se instala y todos estos pasos se realizan automáticamente, pero cuando corresponda, debe realizar los pasos de Varios archivos de origen de función personalizados manualmente.

1. Abra un símbolo del sistema o un shell de Bash y, en la raíz del proyecto, ejecute npm install custom-functions-metadata-plugin.

2. Abra el archivo webpack.config.js y agregue la siguiente línea en la parte superior: const CustomFunctionsMetadataPlugin = require("custom-functions-metadata-plugin");.

3. Desplácese hacia abajo hasta la plugins matriz y agregue lo siguiente a la parte superior de la matriz. Cambie la ruta de acceso y el input nombre de archivo según sea necesario para que coincidan con el proyecto, pero el output valor debe ser "functions.json". Si usa TypeScript, use el nombre de archivo de origen *.ts, no el archivo *.js transpilado.

   new CustomFunctionsMetadataPlugin({
      output: "functions.json",
      input: "./src/functions/functions.js", 
   }),
   

Varios archivos de origen de función personalizados

Si, y solo si ha organizado las funciones personalizadas en varios archivos de origen, hay pasos adicionales.

1. En el archivo webpack.config.js, reemplace el valor de cadena de input por una matriz de direcciones URL de cadena que apunten a cada uno de los archivos. A continuación puede ver un ejemplo:

   new CustomFunctionsMetadataPlugin({
      output: "functions.json",
      input: [
               "./src/functions/someFunctions.js", 
               "./src/functions/otherFunctions.js"
             ], 
   }),
   

2. Desplácese hasta la entry.functions propiedad y reemplace su valor por la misma matriz que usó en el paso anterior. A continuación puede ver un ejemplo:

   entry: {
      polyfill: ["core-js/stable", "regenerator-runtime/runtime"],
      taskpane: ["./src/taskpane/taskpane.js", "./src/taskpane/taskpane.html"],
      functions: [
               "./src/functions/someFunctions.js", 
               "./src/functions/otherFunctions.js"
             ],
    },
   

Ejecución de la herramienta

No tiene que hacer nada para ejecutar la herramienta. Cuando se ejecuta Webpack, crea el archivo functions.json y lo coloca en memoria en modo de desarrollo o en la carpeta /dist en modo de producción.

Conceptos básicos de las etiquetas JSDoc

Agregue la etiqueta @customfunction en los comentarios de código de una función JavaScript o TypeScript para marcarla como una función personalizada.

Los tipos de parámetro de la función se pueden proporcionar utilizando la etiqueta @param en JavaScript, o desde el tipo de función en TypeScript. Para obtener más información, vea las secciones etiqueta @param y Tipos.

Adición de una descripción a una función

La descripción se muestra al usuario como texto de ayuda cuando necesita saber lo que hace la función personalizada. La descripción no requiere ninguna etiqueta específica. Solo tiene que escribir una breve descripción de texto en el comentario JSDoc. En general, la descripción se encuentra al principio de la sección del comentario JSDoc, pero funcionará sin importar dónde se coloque.

Para ver ejemplos de las descripciones de las funciones integradas, abra Excel, vaya a la pestaña Fórmulas y elija Insertar función. Podrá examinar todas las descripciones de las funciones y también ver sus propias funciones personalizadas en la lista.

En el ejemplo siguiente, la frase "Calcula el volumen de una esfera" es la descripción de la función personalizada.

/**
/* Calculates the volume of a sphere.
/* @customfunction VOLUME
...
 */

Etiquetas JSDoc admitidas

Las siguientes etiquetas JSDoc se admiten en las funciones personalizadas de Excel.

• @cancelable
• @customfunctionnombredel identificador
• dirección URLde @helpurl
• @param{type}name description
• @requiresAddress
• @requiresParameterAddresses
• @returns{type}
• @streaming
• @volatile

---

@cancelable

Indica que una función personalizada realiza una acción cuando se cancela la función.

El último parámetro de función debe ser del tipo CustomFunctions.CancelableInvocation. La función puede asignar una función a la oncanceled propiedad para indicar el resultado cuando se cancela la función.

Si el último parámetro de la función es del tipo CustomFunctions.CancelableInvocation, se considerará @cancelable incluso si la etiqueta no está presente.

Una función no puede tener las etiquetas @cancelable y @streaming al mismo tiempo.

@customfunction

Sintaxis: @customfunctionidname

Esta etiqueta indica que la función JavaScript/TypeScript es una función personalizada de Excel. Es necesario crear metadatos para la función personalizada.

A continuación se muestra un ejemplo de esta etiqueta.

/**
 * Increments a value once a second.
 * @customfunction
 * ...
 */

id

id identifica una función personalizada.

• Si no se proporciona el id, el nombre de la función JavaScript o TypeScript se convierte en mayúsculas y se eliminan los caracteres no permitidos.
• El id debe ser único para todas las funciones personalizadas.
• Los caracteres permitidos se limitan a: A-Z, a-z, 0-9, caracteres de subrayado (_) y punto (.).

En el ejemplo siguiente, el incremento es el id y el name de la función.

/**
 * Increments a value once a second.
 * @customfunction INCREMENT
 * ...
 */

name

Proporciona el name (nombre) para mostrar de la función personalizada.

• Si no se proporciona el nombre, el identificador también se usa como el nombre.
• Caracteres permitidos: letras caracteres alfabéticos Unicode, números, punto (.) y subrayado (_).
• Debe comenzar con una letra.
• La longitud máxima es de 128 caracteres.

En el ejemplo siguiente, INC es el id de la función e increment es el name.

/**
 * Increments a value once a second.
 * @customfunction INC INCREMENT
 * ...
 */

descripción

A los usuarios de Excel les aparece una descripción a medida que escriben la función y especifica lo que hace la función. La descripción no requiere ninguna etiqueta específica. Agregue una descripción a una función personalizada mediante una frase en el comentario JSDoc que describa lo que hace la función. De forma predeterminada, cualquier texto que no esté etiquetado en la sección de comentario JSDoc será la descripción de la función.

En el ejemplo siguiente, la frase "Una función que suma dos números" es la descripción de la función personalizada con la propiedad de id de ADD.

/**
 * A function that adds two numbers.
 * @customfunction ADD
 * ...
 */

@helpurl

Sintaxis: @helpurlurl

La dirección url proporcionada se muestra en Excel.

En el ejemplo siguiente, es helpurlhttp://www.contoso.com/weatherhelp.

/**
 * A function which streams the temperature in a town you specify.
 * @customfunction getTemperature
 * @helpurl http://www.contoso.com/weatherhelp
 * ...
 */

@param

JavaScript

Sintaxis de JavaScript: @param { type}name description

• {type} especifica la información de tipo dentro de llaves. Consulte la sección Tipos para obtener más información sobre los tipos que puede usar. Si no se especifica ningún tipo, se usará el tipo any predeterminado.
• name especifica el parámetro al que se aplica la @param etiqueta. Es necesario.
• description proporciona la descripción que aparece en Excel para el parámetro de la función. Es opcional.

Para indicar que un parámetro de función personalizado es opcional, coloque corchetes alrededor del nombre del parámetro. Por ejemplo, @param {string} [text] Optional text.

Nota:

El valor predeterminado para los parámetros opcionales es null.

En el ejemplo siguiente se muestra una función ADD que agrega dos o tres números, con el tercer número como parámetro opcional.

/**
 * A function which sums two, or optionally three, numbers.
 * @customfunction ADDNUMBERS
 * @param firstNumber {number} First number to add.
 * @param secondNumber {number} Second number to add.
 * @param [thirdNumber] {number} Optional third number you wish to add.
 * ...
 */

TypeScript

Sintaxis de TypeScript: @paramdescripción delnombre

• name especifica el parámetro al que se aplica la @param etiqueta. Es necesario.
• description proporciona la descripción que aparece en Excel para el parámetro de la función. Es opcional.

Consulte la sección Tipos para obtener más información sobre los tipos de parámetro de función que puede usar.

Para indicar un parámetro de función personalizada como opcional, siga uno de estos procedimientos:

• Use un parámetro opcional. Por ejemplo: function f(text?: string)
• Dé un valor predeterminado al parámetro. Por ejemplo: function f(text: string = "abc")

Para obtener una descripción detallada del @param, vea: JSDoc

Nota:

El valor predeterminado para los parámetros opcionales es null.

En el ejemplo siguiente se muestra la función add que suma dos números.

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

@requiresAddress

Indica que se debe proporcionar la dirección de la celda donde se evalúa la función.

El último parámetro de función debe ser de tipo CustomFunctions.Invocation o de tipo derivado para usar @requiresAddress. Cuando se llama a la función, la propiedad address contendrá la dirección.

En el ejemplo siguiente se muestra cómo usar el invocation parámetro en combinación con @requiresAddress para devolver la dirección de la celda que invocó la función personalizada. Consulte Parámetro invocación para obtener más información.

/**
 * Return the address of the cell that invoked the custom function. 
 * @customfunction
 * @param {number} first First parameter.
 * @param {number} second Second parameter.
 * @param {CustomFunctions.Invocation} invocation Invocation object. 
 * @requiresAddress 
 */
function getAddress(first, second, invocation) {
  const address = invocation.address;
  return address;
}

@requiresParameterAddresses

Indica que la función debe devolver las direcciones de los parámetros de entrada.

El último parámetro de función debe ser de tipo CustomFunctions.Invocation o de tipo derivado para usar @requiresParameterAddresses. El comentario JSDoc también debe incluir una @returns etiqueta que especifique que el valor devuelto sea una matriz, como @returns {string[][]} o @returns {number[][]}. Consulte Tipos de matriz para obtener información adicional.

Cuando se llama a la función, la parameterAddresses propiedad contendrá las direcciones de los parámetros de entrada.

En el ejemplo siguiente se muestra cómo usar el invocation parámetro en combinación con @requiresParameterAddresses para devolver las direcciones de tres parámetros de entrada. Consulte Detección de la dirección de un parámetro para obtener más información.

/**
 * Return the addresses of three parameters. 
 * @customfunction
 * @param {string} firstParameter First parameter.
 * @param {string} secondParameter Second parameter.
 * @param {string} thirdParameter Third parameter.
 * @param {CustomFunctions.Invocation} invocation Invocation object. 
 * @returns {string[][]} The addresses of the parameters, as a 2-dimensional array.
 * @requiresParameterAddresses
 */
function getParameterAddresses(firstParameter, secondParameter, thirdParameter, invocation) {
  const addresses = [
    [invocation.parameterAddresses[0]],
    [invocation.parameterAddresses[1]],
    [invocation.parameterAddresses[2]]
  ];
  return addresses;
}

@returns

Sintaxis: @returns {type}

Proporciona el tipo de valor devuelto.

Si {type} se omite, se usará la información de tipo TypeScript. Si no hay ninguna información de tipo, el tipo será any.

En el ejemplo siguiente se muestra la función add que usa la etiqueta @returns.

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

@streaming

Se usa para indicar que una función personalizada es una función de transmisión.

El último parámetro es de tipo CustomFunctions.StreamingInvocation<ResultType>. La función devuelve void.

Las funciones de streaming no devuelven valores directamente, sino que llaman mediante setResult(result: ResultType) el último parámetro.

Las excepciones iniciadas por una función de transmisión se ignoran. setResult() se puede llamar con Error para indicar un resultado de error. Para ver un ejemplo de una función de transmisión y más información, vea Crear una función de streaming.

Las funciones de transmisión no se pueden marcar como @volatile.

@volatile

Una función variable es aquella cuyo resultado no es igual de un momento al siguiente, incluso si no toma ningún argumento o los argumentos no se han cambiado. Excel vuelve a evaluar las celdas que contienen funciones volátiles, junto con todos los dependientes, cada vez que actualiza. Por este motivo, confiar demasiado en las funciones volátiles puede hacer que los tiempos de actualización sean lentos, por lo que deben usarse con precaución.

Las funciones de transmisión no pueden ser volátiles.

La siguiente función es volátil y usa la etiqueta @volatile.

/**
 * Simulates rolling a 6-sided die.
 * @customfunction
 * @volatile
 */
function roll6sided(): number {
  return Math.floor(Math.random() * 6) + 1;
}

---

Tipos

Al especificar un tipo de parámetro, Excel convertirá los valores en ese tipo antes de llamar a la función. Si el tipo es any, no se realizará ninguna conversión.

Tipos de valores

Se puede representar un valor único con uno de los siguientes tipos: boolean, number, string.

Tipo de matriz

Use un tipo de matriz bidimensional para que el parámetro o valor devuelto sea una matriz de valores. Por ejemplo, el tipo number[][] indica una matriz de números e string[][] indica una matriz de cadenas.

Tipo de error

Una función de no transmisión puede indicar un error si devuelve un tipo de Error.

Una función de transmisión puede indicar un error al llamar a setResult() con un tipo de Error.

Promesa

Una función personalizada puede devolver una promesa que proporciona el valor cuando se resuelve la promesa. Si se rechaza la promesa, la función personalizada producirá un error.

Otros tipos

Cualquier otro tipo se tratará como un error.

Siguientes pasos

Obtenga información sobre la nomenclatura y localización de funciones personalizadas.

Vea también

• Creación manual de metadatos JSON para funciones personalizadas
• Crear funciones personalizadas en Excel