Tutorial: crear funciones personalizadas en Excel

Cree un complemento de Excel que proporcione funciones personalizadas de JavaScript junto con funciones integradas como SUM. Creará funciones que realizan un cálculo, recuperarán datos de la web y transmitirán actualizaciones en tiempo real a una hoja de cálculo.

En este tutorial:

  • Cree un complemento de función personalizado mediante el generador de Yeoman para complementos de Office.
  • Usar una función personalizada predefinida para realizar un cálculo sencillo.
  • Crear una función personalizada que solicita los datos desde la web.
  • Crear una función personalizada que transmite datos en tiempo real desde la web.

Requisitos previos

  • Node.js (la versión más reciente de Active LTS). Visite el sitioNode.js para descargar e instalar la versión correcta para el sistema operativo.

  • La versión más reciente de Yeoman y Generador de Yeoman para complementos de Office. Para instalar estas herramientas globalmente, ejecute el siguiente comando desde el símbolo del sistema.

    npm install -g yo generator-office

    Nota:

    Incluso si ya ha instalado el generador Yeoman, recomendamos que actualice el paquete de la versión más reciente desde npm.

  • Office está conectado a una suscripción Microsoft 365 (incluido Office en la Web).

    Nota:

    Si aún no tiene Office, puede calificar para una suscripción Microsoft 365 E5 desarrollador a través del Programa para desarrolladores de Microsoft 365; para obtener más información, consulte las preguntas más frecuentes. Como alternativa, puede registrarse para obtener una evaluación gratuita de 1 mes o comprar un plan de Microsoft 365.

Crear un proyecto de funciones personalizadas

Cree el proyecto de código para el complemento de función personalizada. El generador de Yeoman para complementos de Office configura el proyecto con funciones personalizadas precompiladas para probar. Si ya ha generado un proyecto en el inicio rápido de funciones personalizadas, use ese proyecto y continúe en Crear una función personalizada que solicite datos de la web.

Nota:

Si vuelve a crear el proyecto Yo Office, es posible que reciba un error porque la memoria caché de Office ya tiene una instancia de una función con el mismo nombre. Para evitar este error, borre la memoria caché de Office antes de ejecutar npm run start.

  1. Ejecute el siguiente comando para crear un proyecto de complemento con el generador Yeoman. Se agregará una carpeta que contiene el proyecto al directorio actual.

    yo office

    Nota:

    Cuando ejecute el comando yo office, es posible que reciba mensajes sobre las directivas de recopilación de datos de Yeoman y las herramientas de la CLI de complementos de Office. Use la información adecuada que se proporciona para responder a los mensajes.

    Cuando se le pida, proporcione la siguiente información para crear el proyecto de complemento.

    • Elija un tipo de proyecto:Excel Custom Functions using a Shared Runtime
    • Elija un tipo de script:JavaScript
    • ¿Cómo desea asignarle el nombre al complemento?My custom functions add-in

    La interfaz de la línea de comandos del generador de complementos de Office de Yeoman solicita proyectos de funciones personalizadas.

    El generador de Yeoman crea los archivos del proyecto e instala componentes de Node compatibles.

  2. Vaya a la carpeta raíz del proyecto.

    cd "My custom functions add-in"

  3. Cree el proyecto.

    npm run build

    Nota:

    Los complementos de Office deben usar HTTPS y no HTTP, incluso cuando está desarrollando. Si se le pide que instale un certificado después de ejecutar npm run build, acepte el símbolo del sistema para instalar el certificado que proporciona el generador de Yeoman.

  4. Inicie el servidor web local, que se ejecuta en Node.js. Puede probar el complemento de la función personalizada en Excel.

El comando para probar el complemento en Excel en Windows o Mac depende de cuándo creó el proyecto. Si la "scripts" sección del archivo package.json del proyecto tiene un start:desktop script, ejecute npm run start:desktop. De lo contrario, ejecute npm run start. El servidor web local se inicia y Excel se abre con el complemento cargado.

Nota:

  • Los complementos de Office deben usar HTTPS, no HTTP, aunque esté desarrollando. Si se le pide que instale un certificado después de ejecutar uno de los siguientes comandos, acepte el mensaje para instalar el certificado que proporciona el generador de Yeoman. Es posible que también deba ejecutar el símbolo del sistema o el terminal como administrador para que se realicen los cambios.

  • Si es la primera vez que desarrolla un complemento de Office en el equipo, es posible que se le pida en la línea de comandos que conceda a Microsoft Edge WebView una exención de bucle invertido ("Allow localhost loopback for Microsoft Edge WebView?"). Cuando se le solicite, escriba Y para permitir la exención. Tenga en cuenta que necesitará privilegios de administrador para permitir la exención. Una vez permitido, no se le pedirá una exención al transferir localmente complementos de Office en el futuro (a menos que quite la exención de la máquina). Para obtener más información, consulte "No se puede abrir este complemento desde localhost" al cargar un complemento de Office o mediante Fiddler.

    Símbolo del sistema de la línea de comandos para permitir a Microsoft Edge WebView una exención de bucle invertido.

  • Cuando use por primera vez el generador de Yeoman para desarrollar un complemento de Office, el explorador predeterminado abre una ventana en la que se le pedirá que inicie sesión en su cuenta de Microsoft 365. Si no aparece una ventana de inicio de sesión y encuentra un error de tiempo de espera de inicio de sesión o de instalación local, ejecute atk auth login m365.

Prueba de una función personalizada precompilada

El proyecto contiene funciones personalizadas precompiladas en ./src/functions/functions.js. El archivo ./manifest.xml los asigna al CONTOSO espacio de nombres, que se usa para acceder a las funciones en Excel.

A continuación, pruebe la ADD función personalizada completando los pasos siguientes.

  1. En Excel, vaya a cualquier celda y escriba =CONTOSO. Observe que el menú Autocompletar muestra la lista de todas las funciones en el espacio de nombres CONTOSO.

  2. Escriba =CONTOSO.ADD(10,200) en la celda y, a continuación, seleccione Entrar.

La ADD función personalizada devuelve 210.

Si el espacio de nombres CONTOSO no está disponible en el menú autocompletar, siga estos pasos para registrar el complemento en Excel.

  1. SeleccioneComplementos deinicio> y, a continuación, seleccione Más configuración.

  2. En el cuadro de diálogo Complementos de Office , seleccione Cargar mi complemento.

  3. Elija Examinar... y navegue hasta el directorio raíz del proyecto que creó el generador Yeoman.

  4. Seleccione el archivo manifest.xml y elija Abrir, después, seleccione Subir.

  5. Pruebe la nueva función. En la celda B1, escriba el texto =CONTOSO. GETSTARCOUNT("OfficeDev", "Excel-Custom-Functions") y presione Entrar. Debe ver que el resultado en la celda B1 es el número de estrellas actual proporcionado al repositorio de Github de funciones personalizadas de Excel.

Nota:

Consulte la sección Solución de problemas de este artículo si se producen errores al transferir localmente el complemento.

Crear una función personalizada que solicita los datos desde la web

La integración de datos desde la web es una excelente manera de ampliar Excel a través de funciones personalizadas. Cree una getStarCount función personalizada que recupere el número de estrellas de un repositorio de GitHub.

  1. En el proyecto de complemento Mis funciones personalizadas , abra ./src/functions/functions.js en el editor de código.

  2. En functions.js, agregue el código siguiente.

    /**
 * Gets the star count for a GitHub repository.
 * @customfunction
 * @param {string} userName GitHub user or organization name.
 * @param {string} repoName GitHub repository name.
 * @returns {number} Number of stars given to the GitHub repository.
 */
async function getStarCount(userName, repoName) {
  try {
    const url = `https://api.github.com/repos/${userName}/${repoName}`;
    const response = await fetch(url);

    if (!response.ok) {
      throw new Error(response.statusText);
    }

    const jsonResponse = await response.json();
    return jsonResponse.stargazers_count;
  } catch (error) {
    throw new CustomFunctions.Error(CustomFunctions.ErrorCode.notAvailable, String(error));
  }
}

  3. Ejecute el siguiente comando para volver a compilar el proyecto.

    npm run build

  4. Complete los pasos siguientes (para Excel en la web, Windows o Mac) para volver a registrar el complemento en Excel. Debe completar estos pasos antes de que la nueva función esté disponible.

  1. Cierre Excel y vuelva a abrirlo.

  2. En la cinta de Opciones de Excel, seleccioneComplementos deinicio>.

  3. En la sección Complementos para desarrolladores , seleccione El complemento Mis funciones personalizadas para registrarlo.

    El cuadro de diálogo Mis complementos que muestra los complementos activos, con el botón Mi complemento de función personalizada resaltado.

  4. En la celda B1, escriba =CONTOSO.GETSTARCOUNT("OfficeDev", "Office-Add-in-Samples")y, a continuación, seleccione Entrar. La celda muestra el número actual de estrellas para el repositorio Office-Add-in-Samples.

Nota:

Consulte la sección Solución de problemas de este artículo si se producen errores al transferir localmente el complemento.

Crear una función personalizada asincrónica de transmisión de datos

La getStarCount función devuelve el número de estrellas en un momento específico. Por el contrario, una función de streaming puede actualizar una celda repetidamente. Incluye un invocation parámetro que representa la celda que llamó a la función .

El ejemplo siguiente contiene dos funciones. currentTime devuelve la hora actual como una cadena. La función de streaming clock llama invocation.setResult a para actualizar la celda cada segundo y usa invocation.onCanceled para detener el temporizador cuando Excel cancela la función.

El proyecto de complemento Mis funciones personalizadas ya contiene estas funciones en ./src/functions/functions.js.

/**
 * Returns the current time
 * @returns {string} String with the current time formatted for the current locale.
 */
function currentTime() {
  return new Date().toLocaleTimeString();
}

/**
 * Displays the current time once a second.
 * @customfunction
 * @param {CustomFunctions.StreamingInvocation<string>} invocation Custom function invocation
 */
function clock(invocation) {
  const timer = setInterval(() => {
    const time = currentTime();
    invocation.setResult(time);
  }, 1000);

  invocation.onCanceled = () => {
    clearInterval(timer);
  };
}

Para probar la función de streaming, escriba =CONTOSO.CLOCK() en la celda C1 y, a continuación, seleccione Entrar. La celda muestra la hora actual y se actualiza cada segundo. Puede usar el mismo patrón de temporizador con funciones que solicitan datos en tiempo real desde la web.

Solución de problemas

Es posible que encuentre problemas si ejecuta el tutorial varias veces. Si la memoria caché de Office ya tiene una instancia de una función con el mismo nombre, el complemento recibe un error al transferir localmente.

Para evitar este conflicto, borre la memoria caché de Office antes de ejecutar npm run start. Si el proceso de npm ya está en ejecución, escriba npm run stop, borre la caché de Office y reinicie npm.

Un mensaje de error en Excel titulado

Pasos siguientes

Ha creado un nuevo proyecto de funciones personalizadas, ha probado una función precompilada, ha creado una función personalizada que solicita datos de la web y ha creado una función personalizada que transmite datos. A continuación, obtenga información sobre cómo compartir datos de funciones personalizadas con el panel de tareas.

  • Last updated on