Si te estás planteando crear tus propios complementos para Office, seguramente ya te habrás dado cuenta de que no es solo “hacer un poco de código” y listo. Un add-in de Office profesional implica entender la plataforma, la API de JavaScript, el manifiesto y las herramientas de desarrollo que ofrece Microsoft, además de saber cómo probarlo, depurarlo y, por supuesto, cómo hacer que la experiencia de usuario sea agradable.
A lo largo de esta guía vamos a recorrer el camino completo, desde el primer prototipo hasta tener un complemento listo para usarse en Word, Excel, Outlook y otras aplicaciones de Microsoft 365. Verás qué herramientas tienes a tu disposición (Yeoman, Visual Studio, Agents Toolkit, el Kit de desarrollo para Visual Studio Code), cómo se estructura internamente un add-in, cómo se conecta con la API de Office y qué pasos seguir para ejecutarlo y depurarlo tanto en escritorio como en la web.
La plataforma de complementos de Office: el punto de partida
Todos los add-ins modernos de Office se construyen sobre la plataforma de complementos de Office, que es la base común para Word, Excel, Outlook, PowerPoint, OneNote y Project. Esto significa que la misma arquitectura se reutiliza en distintas apps, y que muchas piezas del desarrollo están estandarizadas.
Antes de escribir una sola línea de código, conviene tener claros algunos conceptos clave: qué aplicaciones y plataformas son compatibles, qué patrones de programación ofrece la API de JavaScript de Office, cómo se define el manifiesto del complemento y de qué forma se diseña la interfaz (paneles de tareas, cuadros de diálogo, pestañas personalizadas, etc.). Todo este ciclo de vida de desarrollo es el marco mental que vas a usar para ir del prototipo al add-in real.
¿Cómo se crean los complementos para Office?
Para arrancar tu proyecto tienes varias rutas oficiales, cada una pensada para distintos perfiles de desarrollador, pero todas con un objetivo común: generar una solución de complemento basada en HTML, CSS y JavaScript (o TypeScript) que se integre con Office. Las principales opciones que Microsoft ofrece actualmente son:
- Generador de Yeoman para complementos de Office.
- Visual Studio (con soporte específico para Office Add-ins).
- Microsoft 365 Agents Toolkit.
- Kit de desarrollo de complementos de Office para Visual Studio Code.
Generador de Yeoman para complementos de Office
El generador de Yeoman para Office es ideal si te mueves cómodo en entornos web y línea de comandos. Yeoman crea por ti un proyecto Node.js totalmente funcional que puedes abrir en Visual Studio Code o en cualquier editor, con toda la estructura (manifiesto, panel de tareas, estilos y scripts) lista para empezar a personalizar.
Con este generador puedes crear complementos para Excel, OneNote, Outlook, PowerPoint, Project, Word y también proyectos de funciones personalizadas de Excel. A la hora de configurar el proyecto, puedes optar por una plantilla sencilla con HTML, CSS y JavaScript (o TypeScript) o montar el esqueleto con React, eligiendo igualmente entre JavaScript y TypeScript según lo que prefieras.
Para empezar a usar Yeoman necesitas tener Node.js en su versión LTS instalada en tu sistema, y después instalar globalmente Yeoman y el generador específico de Office con npm. Desde una consola, esto se hace lanzando:
npm install -g yo generator-office
Una vez configurado el entorno, solo tienes que ejecutar en el directorio deseado:
yo office
Durante el asistente se te pedirá información como el tipo de proyecto (por ejemplo, Office Add-in Task Pane project), el tipo de script (JavaScript o TypeScript), el nombre del complemento y la aplicación de Office a la que se orienta (Word, Excel, Outlook, etc.). Con tus respuestas, Yeoman generará la carpeta del proyecto, instalará las dependencias Node necesarias y dejará el complemento listo para ejecutarse y probarse.
Visual Studio para complementos de Office
Si prefieres una experiencia más clásica y un IDE completo, Visual Studio incluye plantillas para crear complementos de Office para Excel, Outlook, Word y PowerPoint. En este caso, el proyecto de add-in forma parte de una solución de Visual Studio y se trabaja igualmente con HTML, CSS y JavaScript como tecnologías de interfaz y lógica.
La ventaja de este enfoque es que aprovechas las herramientas integradas de Visual Studio para depuración, administración de proyectos, soporte de tipos y publicación. Así que, si ya vienes del mundo .NET o sueles trabajar con soluciones complejas, puede que te resulte más cómodo este camino.
Microsoft 365 Agents Toolkit
Otra opción especialmente interesante si quieres ir más allá del add-in tradicional es el Microsoft 365 Agents Toolkit, una caja de herramientas pensada para crear extensiones de Microsoft 365 en sentido amplio. Con esta solución no solo puedes desarrollar complementos de Office, sino casi cualquier tipo de extensión que interactúe con los servicios de Microsoft 365.
Con este toolkit es posible generar proyectos de complementos de Office con plantillas y asistentes pensados para integraciones avanzadas, por ejemplo, escenarios donde tu complemento participa de flujos de trabajo más amplios o interactúa con otros servicios en la nube dentro del ecosistema 365.
Kit de desarrollo de complementos de Office para Visual Studio Code
Si tu entorno natural es VS Code, tienes a tu disposición una extensión oficial: el Kit de desarrollo de complementos de Office, que se integra directamente en la barra de actividad de Visual Studio Code. Con esta extensión puedes crear nuevos proyectos de add-ins y cargar ejemplos rápidamente desde el propio editor.
Al pulsar en la opción correspondiente dentro de la extensión, se abre un asistente que genera tu proyecto de complemento, lo sitúa en la carpeta de trabajo que elijas y lo abre en una nueva ventana de Visual Studio Code. Esa nueva ventana contendrá ya la estructura del proyecto, normalmente con un ejemplo de panel de tareas básico para que entiendas la arquitectura.
A partir de ahí puedes revisar archivos clave como manifest.xml o manifest.json en la raíz del proyecto (donde se configura el complemento), y los ficheros que definen el panel de tareas: ./src/taskpane/taskpane.html para el marcado, ./src/taskpane/taskpane.css para los estilos y ./src/taskpane/taskpane.js para el código que usa la API de Office.
Las dos piezas fundamentales de un complemento de Office
Todo add-in de Office moderno se compone, a grandes rasgos, de dos bloques principales: un manifiesto que declara cómo se integra el complemento con Office y una aplicación web que define la interfaz de usuario y la lógica.
- El manifiesto de complemento describe la configuración, metadatos, permisos, puntos de integración y comportamiento del add-in.
- La aplicación web es el conjunto de páginas HTML, scripts y estilos que se muestran en paneles de tareas, complementos de contenido, cuadros de diálogo y otros contenedores dentro de Office.
La aplicación web utiliza la API de JavaScript de Office para interactuar con el documento (o el mensaje de correo, en el caso de Outlook) en el que está ejecutándose el complemento. Además, como cualquier aplicación web, puede autenticarse frente a servicios externos, consumir APIs REST, trabajar con identidad de usuario y mucho más.
El manifiesto: configuración y capacidades del complemento
El manifiesto define prácticamente todo lo que Office necesita saber sobre tu solución, así que es un archivo crítico. En él se incluyen los metadatos (ID, nombre, descripción, versión, configuración regional predeterminada) y también la relación de aplicaciones de Office donde se puede cargar el complemento.
En el manifiesto también se establecen los permisos que requiere el add-in, la forma en que se integra con la interfaz de Office y cualquier UI personalizada que añada. Esto incluye pestañas específicas en la cinta, botones extra, menús contextuales o comandos de complemento.
Otro aspecto que se controla desde el manifiesto son las imágenes usadas para la iconografía del complemento, la personalización de marca y las dimensiones de los contenedores (por ejemplo, el tamaño de un complemento de contenido o la altura preferida de un add-in de Outlook).
En el caso concreto de Outlook, en el manifiesto puedes definir reglas que deciden cuándo se activa el complemento según el contexto de un mensaje o una cita, y para aplicaciones como Excel y Word es posible declarar métodos abreviados de teclado específicos que disparen funcionalidades del add-in.
La aplicación web y la interacción con el documento de Office
La segunda parte clave es la aplicación web, que es la que el usuario ve y con la que interactúa. Esta app se aloja normalmente en un servidor web (puede ser local en desarrollo, o en la nube en producción) y se renderiza en paneles de tareas, cuadros de diálogo o regiones de contenido dentro de Office.
Para poder hablar con el documento, la aplicación web se apoya en la API de JavaScript de Office, que se importa mediante un script alojado en el CDN oficial. La ruta típica es:
https://appsforoffice.microsoft.com/lib/1/hosted/office.js
En cualquier página web del complemento donde quieras usar la API, debes hacer referencia a este archivo dentro de una etiqueta <script> en el <head> del documento HTML, por ejemplo:
<head>...<script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js" type="text/javascript"></script>...</head>
A partir de ahí ya puedes usar los objetos y métodos expuestos por Office.js para leer y modificar el contenido, mostrar diálogos, usar configuraciones del cliente y mucho más.
Dos modelos de API: específicas de aplicación y comunes
La API de JavaScript para Office no es un único bloque homogéneo; se organiza en dos modelos distintos con objetivos complementarios. Por un lado, tenemos las API específicas de cada aplicación (Excel, Word, etc.) y, por otro, las API comunes que funcionan en varios hosts.
Las API específicas de aplicación ofrecen objetos fuertemente tipados que representan entidades propias de cada programa (por ejemplo, hojas, rangos, tablas y gráficos en Excel). Este modelo se introdujo con Office 2016 y utiliza promesas, permitiendo agrupar varias operaciones en una sola llamada para mejorar el rendimiento, especialmente en Office en la web.
Por su parte, las API comunes permiten acceder a partes de la experiencia que son compartidas entre distintas aplicaciones: elementos de interfaz, cuadros de diálogo, configuración del cliente e incluso funcionalidades para interactuar con Outlook, PowerPoint o Project bajo un mismo modelo. En este caso, el patrón es más clásico, basado en callbacks, y suele permitir solo una operación por solicitud. Estas APIs comunes aparecieron con Office 2013 y siguen siendo relevantes cuando quieres que tu complemento funcione en el mayor número posible de aplicaciones.
Conjuntos de requisitos de la API
Dentro del mundo Office.js, las funcionalidades se agrupan en conjuntos llamados requirement sets. Un conjunto de requisitos es, básicamente, un grupo con nombre de miembros de la API que representan una determinada versión o bloque de capacidades.
Hay conjuntos orientados a una aplicación concreta, como por ejemplo ExcelApi 1.7, que solo se puede usar en Excel, y otros de carácter transversal, como DialogApi 1.1, que sirve para manejar cuadros de diálogo en cualquier aplicación que lo soporte.
Desde tu complemento puedes comprobar estos conjuntos de requisitos para determinar si la aplicación y la plataforma donde se está ejecutando soportan las funciones que necesitas. Esto es clave cuando quieres mantener compatibilidad con versiones distintas de Office, tanto en escritorio como en web o en otras plataformas.
La compatibilidad de los requirement sets depende de la aplicación concreta (Word, Excel, etc.), la versión instalada y el sistema operativo o entorno de ejecución. La documentación oficial de Microsoft detalla para cada combinación qué conjuntos y APIs están disponibles.
Explorar la API con Script Lab
Si quieres experimentar rápidamente sin tener que montar un proyecto completo, tienes a tu disposición Script Lab. Script Lab es un complemento gratuito para Office que te deja escribir, ejecutar y probar fragmentos de código Office.js directamente desde aplicaciones como Excel o Word.
Al instalarlo desde Microsoft Marketplace, verás que ofrece una biblioteca de ejemplos ya preparados para distintas operaciones típicas: manipular rangos, trabajar con tablas, mostrar diálogos, etc. Puedes ejecutar estos fragmentos tal cual, modificarlos o usarlos como punto de partida para el código de tu propio complemento.
Esta herramienta es especialmente útil en la fase de prototipo, porque te permite validar rápidamente si una API hace lo que necesitas, ver cómo se comporta en Office en la web o en escritorio y ajustar tu lógica antes de integrarla en el proyecto real.
Extender la interfaz de usuario de Office con tu complemento
Uno de los grandes atractivos de los complementos de Office es su capacidad para ampliar la interfaz de usuario y engancharse a la experiencia nativa de Word, Excel u Outlook. Esa extensión de la UI se basa principalmente en comandos de complemento y en contenedores HTML como paneles de tareas, complementos de contenido y cuadros de diálogo.
Los comandos de complemento te permiten agregar una pestaña personalizada, botones propios y menús adicionales a la cinta de la aplicación o incluso ampliar los menús contextuales que aparecen al hacer clic derecho sobre texto u objetos (por ejemplo, celdas de Excel). Cuando el usuario pulsa uno de esos comandos, se dispara la acción asociada: ejecutar una función JavaScript, abrir un panel de tareas o lanzar un cuadro de diálogo.
Por otro lado, los contenedores HTML (paneles de tareas, complementos de contenido y cuadros de diálogo) son el “espacio” donde se muestra la interfaz de tu web app. El contenido de cada contenedor procede de una página web alojada en tu servidor, que puede usar la API de Office, llamar a servicios externos, autenticar usuarios y realizar cualquier lógica propia de una aplicación web moderna.
En la práctica puedes tener, por ejemplo, un botón en la cinta que abre un panel de tareas a la derecha del documento, junto con un cuadro de diálogo emergente y un complemento de contenido incrustado directamente en la superficie del documento. Todo ello coordinado mediante JavaScript y Office.js.
Crear proyectos de complemento en Visual Studio Code con el Kit de desarrollo
Cuando trabajas con el Kit de desarrollo de complementos de Office en Visual Studio Code, el flujo típico es bastante directo. Primero necesitas cumplir los requisitos previos (Node.js, extensión instalada, Office conectado a Microsoft 365) y después de eso puedes lanzar el asistente de creación de proyecto desde el icono del kit en la barra de actividad.
Tras seleccionar la opción de crear un nuevo complemento, se te pedirá que elijas el tipo de proyecto, el nombre y la carpeta de trabajo. Una vez confirmados estos datos, la extensión genera automáticamente el proyecto, instala las dependencias necesarias y abre la solución en una segunda ventana de Visual Studio Code (conviene cerrar la primera para evitar confusiones).
Dentro del proyecto encontrarás siempre algunos archivos clave: el manifiesto (manifest.xml o manifest.json) en la raíz y los ficheros del panel de tareas en la carpeta src/taskpane. El HTML define la estructura del panel, la hoja CSS controla el aspecto visual y el archivo JavaScript contiene las llamadas a la API Office.js que conectan la interfaz con la aplicación cliente de Office.
Ejecutar y detener la vista previa con el Kit de desarrollo
Para probar el complemento desde VS Code, se usa el propio kit de desarrollo. Simplemente seleccionas el icono de la extensión, eliges la opción “Vista previa del complemento de Office (F5)” y luego indicas la aplicación de destino, por ejemplo “Excel Desktop (Edge Chromium)” o “Word Desktop (Edge Chromium)”.
La extensión se encarga de verificar que se cumplen los requisitos previos, arrancar el servidor web local, registrar el complemento y lanzar la aplicación de escritorio de Office con el add-in cargado desde tu entorno local. La primera vez puede tardar unos minutos, porque se instalan dependencias y puede que tengas que aceptar la instalación de un certificado local.
Cuando termines de probar o depurar, es importante detener correctamente la vista previa desde la propia extensión, usando la opción “Detener la vista previa del complemento de Office”. Esto cierra el servidor, elimina el complemento del registro y limpia la caché. Después de eso ya puedes cerrar la aplicación de Office con tranquilidad.
Si algo falla al ejecutar el complemento, lo habitual es revisar el terminal integrado de VS Code. Si persisten los problemas, se recomienda cerrar todas las instancias de Office abiertas y detener cualquier servidor antiguo del kit de desarrollo antes de volver a iniciar la vista previa. Para incidencias más complicadas existe documentación de solución de problemas y, en última instancia, siempre puedes abrir un issue en GitHub para obtener ayuda.
Crear un complemento con Yeoman: de “Hola, mundo” a algo más complejo
Cuando usas Yeoman para generar un complemento, el proceso práctico sigue una secuencia bastante clara. Tras instalar Node.js, Yeoman y el generador de Office, ejecutas el comando yo office, respondes a unas cuantas preguntas y obtienes una carpeta con un proyecto ejecutable.
En el ejemplo típico de Word, podrías elegir un Office Add-in Task Pane project con JavaScript, llamarlo “My Office Add-in” y seleccionar Word como aplicación cliente. El generador creará el esqueleto del complemento y ejecutará un npm install inicial para dejar las dependencias preparadas.
Para explorar lo que se ha creado, basta con acceder a la carpeta del proyecto y abrir los archivos principales: el manifiesto (manifest.xml o manifest.json), el HTML del panel de tareas, su CSS y el script JavaScript que contiene las llamadas a Office.js. Normalmente el ejemplo incluye una acción simple, como escribir “Hola, mundo” en el documento o cambiar el estilo de un texto.
La ejecución se hace desde línea de comandos. En el directorio raíz del proyecto puedes lanzar npm start para iniciar el servidor local y abrir Word con el complemento cargado. Si quieres probarlo en Office en la web, existe también una variante de comando que incluye la URL de un documento en OneDrive o SharePoint:
npm run start -- web --document {url}
Una vez en Word, si el panel de tareas de tu complemento no aparece automáticamente, puedes abrir un documento nuevo, ir a la pestaña Inicio y pulsar el botón “Mostrar panel de tareas” de tu add-in. En el panel suele haber un enlace o botón “Ejecutar” que dispara la funcionalidad de ejemplo (por ejemplo, insertar “Hola, mundo” en azul).
Cuando quieras detener el servidor local y desinstalar el complemento, puedes usar el comando npm stop, que cierra el servidor y, en el caso habitual, quita el add-in registrado para esa sesión. Si en algún momento lo cargaste manualmente como complemento local en Office en la web, tendrás que seguir el procedimiento de eliminación manual desde la propia interfaz de Office.
A veces, la instalación automática de dependencias que hace Yeoman (npm install) puede fallar. Si ves errores al ejecutar npm start, lo más sencillo es ir a la carpeta del proyecto y lanzar tú mismo npm install para resolver los módulos que falten. Es normal que aparezcan algunas advertencias durante la instalación; en la mayoría de casos no impiden que todo funcione.
Si quieres afinar las versiones de los paquetes y limpiar dependencias obsoletas, puedes recurrir a npm-check-updates (ncu) para revisar y actualizar las dependencias en bloque. El flujo sería instalar ncu de forma global, ejecutar ncu -u en la raíz del proyecto y finalmente volver a correr npm install.
Primer complemento de Outlook con Yeoman
El caso de Outlook tiene su propio matiz, sobre todo por la variedad de clientes disponibles: Outlook en la web, el nuevo Outlook en Windows, Outlook clásico en Windows y Outlook en Mac. Todos ellos pueden usar el mismo complemento si cumples los requisitos previos.
El proceso de creación con Yeoman es muy similar al de Word. Instalas Node.js, Yeoman y el generador de Office, ejecutas yo office y esta vez eliges Outlook como aplicación cliente. De nuevo seleccionas un proyecto tipo panel de tareas, defines el nombre del complemento y, además, decides qué tipo de manifiesto quieres usar (por ejemplo, “Unified manifest for Microsoft 365” o “Add-in only manifest” según tu escenario).
El generador te dejará preparado un proyecto con su manifiesto (JSON o XML), el HTML del panel de tareas, los estilos y el JavaScript que usa la API de Office para acceder al mensaje seleccionado. El ejemplo básico suele mostrar al menos una propiedad del correo, como el asunto, en el propio panel de tareas.
npm start
Este comando arranca el servidor web local y registra el complemento para que se cargue automáticamente en Outlook. Después te diriges a un mensaje en el Panel de lectura o abres uno en una ventana aparte, y allí buscas el botón “Mostrar panel de tareas” correspondiente a tu add-in. La ubicación varía según el cliente:
- En Outlook en la web y nuevo Outlook para Windows, normalmente accedes desde la barra de acciones del mensaje, en el menú de aplicaciones.
- En Outlook clásico para Windows, el botón suele aparecer en la pestaña Inicio o Mensaje de la cinta.
- En Outlook para Mac, verás el nombre del complemento en la cinta; quizá tengas que desplegar el menú de puntos suspensivos para encontrarlo.
Al abrir el panel de tareas se cargará la interfaz de tu complemento y podrás pulsar en el enlace o botón “Ejecutar” para que, por ejemplo, se muestre el asunto del correo dentro del propio panel. Es una forma rápida de comprobar que la API de Outlook está funcionando y que tu add-in recibe el contexto del mensaje seleccionado.
Para detener el servidor local y desinstalar el complemento, puedes usar npm stop en la consola, que se encarga de cerrar el servidor y limpiar el registro del add-in si este se instaló mediante npm start. Si hubieses cargado el complemento de forma manual, deberás seguir el proceso de eliminación manual en la aplicación de Outlook correspondiente.
Los mismos consejos de solución de problemas aplican aquí: si npm install falla al principio, ejecútalo manualmente, ignora advertencias no críticas y recurre a npm-check-updates si quieres actualizar dependencias de forma controlada. Además, la documentación oficial recoge ejemplos de código más elaborados, como un complemento “Hola mundo” específico para Word o tutoriales más avanzados para Outlook.
Cómo encontrar y usar tu complemento dentro de Office
Una vez que tu complemento está instalado o cargado en la cuenta de Microsoft 365, el siguiente paso es localizarlo dentro de la aplicación. Lo primero es asegurarte de que has iniciado sesión en Office con la cuenta adecuada, ya que muchos complementos se asocian al usuario o a la suscripción.
En aplicaciones como Word, Excel o PowerPoint, el camino estándar es ir al menú Insertar > Mis complementos, donde se muestra el cuadro “Complementos para Office”. Desde ahí puedes buscar tu add-in por nombre; si no aparece a la primera, conviene revisar que estás correctamente autenticado y pulsar el botón de actualizar para recargar la lista.
Una vez localices el complemento en la lista, basta con hacer doble clic para iniciarlo y que se cargue en el documento. A partir de ese momento ya podrás usarlo igual que hiciste durante las pruebas locales, pero apuntando al entorno de producción o al hospedaje que hayas configurado para la aplicación web del add-in.
Con todo este recorrido ya tienes una visión completa del proceso: desde la elección de herramientas (Yeoman, Visual Studio, Agents Toolkit o el Kit para VS Code), pasando por la estructura interna de un complemento (manifiesto más aplicación web), hasta la interacción con Office mediante Office.js, los requirement sets y Script Lab, además de los flujos prácticos para probar, depurar y ejecutar add-ins en Word, Excel u Outlook tanto en escritorio como en la web; con estas bases bien asentadas, convertir un simple prototipo en un complemento de Office listo para producción se vuelve un camino bastante más claro y asumible. Comparte esta información y otras personas conocerán del terma.