Crear el primer complemento de Outlook

Este artículo le guiará a través del proceso de creación de un complemento de panel de tareas de Outlook que muestre al menos una propiedad de un mensaje seleccionado.

Crear el complemento

Puede crear un complemento de Office con el generador de Yeoman para complementos de Office o Visual Studio. El generador Yeoman crea un proyecto de Node.js que se puede administrar con Visual Studio Code u otro editor, mientras que Visual Studio crea una solución de Visual Studio. Seleccione la pestaña del que le gustaría usar y, después, siga las instrucciones para crear el complemento y probarlo localmente.

Generador de Yeoman

Requisitos previos

• Node.js (la última versión de LTS). Visite el sitio deNode.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 de desarrollador Microsoft 365 E5 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.

• Outlook 2016 o posterior en Windows (conectado a una cuenta de Microsoft 365), Outlook en Mac, Outlook en la Web o nuevo Outlook en Windows (versión preliminar).

Creación del proyecto de complemento

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 - Office Add-in Task Pane project

   • Elija un tipo de script - JavaScript

   • ¿Qué nombre quiere asignar al complemento? - My Office Add-in

   • ¿Qué aplicación cliente de Office desea admitir? - Outlook

   

   Después de completar el asistente, el generador creará el proyecto e instalará componentes auxiliares de Node.

   Nota:

   Si usa Node.js versión 20.0.0 o posterior, es posible que vea una advertencia cuando el generador ejecute la instalación de que tiene un motor no admitido. Estamos trabajando en una solución para esto. Mientras tanto, la advertencia no afecta al generador ni al proyecto que se genera, por lo que se puede omitir.

   Sugerencia

   Se pueden pasar por alto las instrucciones de los pasos siguientes que el generador de Yeoman ofrece después de que se haya creado el proyecto de complemento. Las instrucciones paso a paso de este artículo le dan toda la información que necesitará para completar este tutorial.

2. Navegue hasta la carpeta raíz del proyecto de la aplicación web.

   cd "My Office Add-in"
   

Explorar el proyecto

El proyecto de complemento que ha creado con el generador Yeoman contiene código de ejemplo para un complemento de panel de tareas muy básico.

• El archivo ./manifest.xml en el directorio raíz del proyecto define la configuración y las funciones del complemento.
• El archivo ./src/taskpane/taskpane.html contiene el marcado HTML para el panel de tareas.
• El archivo ./src/taskpane/taskpane.css contiene la CSS que se aplica al contenido en el panel de tareas.
• El archivo ./src/taskpane/taskpane.js contiene el código de la API de JavaScript de Office que facilita la interacción entre el panel de tareas y Outlook.

Actualizar el código

1. Abra el proyecto en VS Code o en el editor de código que prefiera.

   Sugerencia

   En Windows, puede navegar hasta el directorio raíz del proyecto desde la línea de comandos y, después, puede escribir code . para abrir esa carpeta en VS Code. En un equipo Mac, necesitará agregar el comando code a la ruta de acceso antes de poder usar ese comando para abrir la carpeta de proyecto en VS Code.

2. Abra el archivo ./src/taskpane/taskpane.html y reemplace todo <el elemento principal> (dentro del <elemento body> ) por el marcado siguiente. Este nuevo marcado agrega una etiqueta donde la secuencia de comandos ./src/taskpane/taskpane.js escribirá los datos.

   <main id="app-body" class="ms-welcome__main" style="display: none;">
       <h2 class="ms-font-xl"> Discover what Office Add-ins can do for you today! </h2>
       <p><label id="item-subject"></label></p>
       <div role="button" id="run" class="ms-welcome__action ms-Button ms-Button--hero ms-font-xl">
           <span class="ms-Button-label">Run</span>
       </div>
   </main>
   

3. En el editor de código, abra el archivo ./src/taskpane/taskpane.jsy agregue el código siguiente a la función de ejecución . Este código utiliza la API JavaScript de Office para obtener una referencia del mensaje actual y escribir su valor de propiedad subject en el panel de tareas.

   // Get a reference to the current message
   const item = Office.context.mailbox.item;
   
   // Write message property value to the task pane
   document.getElementById("item-subject").innerHTML = "<b>Subject:</b> <br/>" + item.subject;
   

   El archivo taskpane.js ahora debe contener el código siguiente.

   /*
    * Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
    * See LICENSE in the project root for license information.
    */
   
   /* global document, Office */
   
   Office.onReady((info) => {
     if (info.host === Office.HostType.Outlook) {
       document.getElementById("sideload-msg").style.display = "none";
       document.getElementById("app-body").style.display = "flex";
       document.getElementById("run").onclick = run;
     }
   });
   
   export async function run() {
     // Get a reference to the current message
     const item = Office.context.mailbox.item;
   
     // Write message property value to the task pane
     document.getElementById("item-subject").innerHTML = "<b>Subject:</b> <br/>" + item.subject;
   }
   

Pruébelo

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.

1. Ejecute el siguiente comando en el directorio principal del proyecto. Al ejecutar este comando, se inicia el servidor web local y el complemento se carga de forma local.

   npm start
   

   Nota:

   Si el complemento no se ha descargado de forma local automáticamente, siga las instrucciones de Transferencia local de complementos de Outlook para realizar pruebas para transferir manualmente el complemento en Outlook.

2. En Outlook, vea un mensaje en el Panel de lecturao abra el mensaje en su propia ventana.

3. Elija la pestaña Inicio (o la pestaña Mensaje si abrió el mensaje en una nueva ventana) y, a continuación, elija el botón Mostrar panel de tareas de la cinta de opciones para abrir el panel de tareas del complemento.

   

4. Cuando se le solicite el cuadro de diálogo WebView Stop On Load, seleccione Aceptar.

   Nota:

   Si selecciona Cancelar, no se volverá a mostrar el cuadro de diálogo mientras se esté ejecutando esta instancia del complemento. Sin embargo, si reinicia el complemento, verá el cuadro de diálogo de nuevo.

5. Desplácese hasta la parte inferior del panel de tareas y seleccione el vínculo Ejecutar para escribir el asunto del mensaje en el panel de tareas.

   

   

Pasos siguientes

Enhorabuena, ha creado correctamente su primer complemento de Outlook. Ahora, obtenga más información sobre las funcionalidades de un complemento de Outlook y cree un complemento más complejo siguiendo el tutorial de complementos de Outlook.

Visual Studio

Requisitos previos

• Visual Studio 2019 o posterior con la carga de trabajo de desarrollo de Office/SharePoint instalada

  Nota:

  Si ya ha instalado Visual Studio 2019 o una versión posterior, use la Instalador de Visual Studio para asegurarse de que está instalada la carga de trabajo de desarrollo de Office/SharePoint.

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

Creación del proyecto de complemento

1. En la barra de menús de Visual Studio, seleccione Archivo>Nuevo>Proyecto.

2. En la lista de tipos de proyecto en Visual C# o Visual Basic, expanda Office/SharePoint, elija Complementos y, luego, Complemento Outlook Web como el tipo de proyecto.

3. Asigne un nombre al proyecto y luego seleccione Aceptar.

4. Visual Studio crea una solución, y los dos proyectos que contiene aparecen en el Explorador de soluciones. El archivo MessageRead.html se abre en Visual Studio.

Explorar la solución de Visual Studio

Una vez que haya completado el asistente, Visual Studio crea una solución que contiene dos proyectos.

Proyecto	Descripción
Proyecto de complemento	Contiene solo un archivo de manifiesto XML, que contiene a su vez todos los ajustes de configuración que describen el complemento. Esta configuración permite a la aplicación de Office determinar cuándo debe activar el complemento y dónde debe aparecer. Visual Studio genera los contenidos de este archivo para que pueda ejecutar el proyecto y usar su complemento inmediatamente. Puede cambiar esta configuración en cualquier momento modificando el archivo XML.
Proyecto de aplicación web	Contiene las páginas de contenido de su complemento, incluidos todos los archivos y referencias de archivos que necesita para desarrollar HTML compatible con Office y páginas de JavaScript. Mientras desarrolla el complemento, Visual Studio hospeda la aplicación web en el servidor local de Internet Information Services (IIS). Cuando esté listo para publicar el complemento, deberá implementar el proyecto de aplicación web en un servidor web.

Actualizar el código

1. MessageRead.html especifica el código HTML que se representará en el panel de tareas del complemento. En MessageRead.html, reemplace el elemento body<> por el marcado siguiente y guarde el archivo.

   <body class="ms-font-m ms-welcome">
       <div class="ms-Fabric content-main">
           <h1 class="ms-font-xxl">Message properties</h1>
           <table class="ms-Table ms-Table--selectable">
               <thead>
                   <tr>
                       <th>Property</th>
                       <th>Value</th>
                   </tr>
               </thead>
               <tbody>
                   <tr>
                       <td><strong>Id</strong></td>
                       <td class="prop-val"><code><label id="item-id"></label></code></td>
                   </tr>
                   <tr>
                       <td><strong>Subject</strong></td>
                       <td class="prop-val"><code><label id="item-subject"></label></code></td>
                   </tr>
                   <tr>
                       <td><strong>Message Id</strong></td>
                       <td class="prop-val"><code><label id="item-internetMessageId"></label></code></td>
                   </tr>
                   <tr>
                       <td><strong>From</strong></td>
                       <td class="prop-val"><code><label id="item-from"></label></code></td>
                   </tr>
               </tbody>
           </table>
       </div>
   </body>
   

2. Abra el archivo MessageRead.js en la raíz del proyecto de aplicación web. Este archivo especifica el script del complemento. Reemplace todo el contenido por el siguiente código y guarde el archivo.

   'use strict';
   
   (function () {
   
       Office.onReady(function () {
           // Office is ready
           $(document).ready(function () {
               // The document is ready
               loadItemProps(Office.context.mailbox.item);
           });
       });
   
       function loadItemProps(item) {
           // Write message property values to the task pane
           $('#item-id').text(item.itemId);
           $('#item-subject').text(item.subject);
           $('#item-internetMessageId').text(item.internetMessageId);
           $('#item-from').html(item.from.displayName + " <" + item.from.emailAddress + ">");
       }
   })();
   

3. Abra el archivo MessageRead.css en la raíz del proyecto de aplicación web. Este archivo especifica los estilos personalizados del complemento. Reemplace todo el contenido por el siguiente código y guarde el archivo.

   html,
   body {
       width: 100%;
       height: 100%;
       margin: 0;
       padding: 0;
   }
   
   td.prop-val {
       word-break: break-all;
   }
   
   .content-main {
       margin: 10px;
   }
   

Actualizar el manifiesto

1. Abra el archivo de manifiesto XML en el proyecto del complemento. Este archivo define las capacidades y la configuración del complemento.

2. El <elemento ProviderName> tiene un valor de marcador de posición. Reemplácelo por su nombre.

3. El atributo DefaultValue del <elemento DisplayName> tiene un marcador de posición. Reemplácelo por My Office Add-in.

4. El atributo DefaultValue del <elemento Description> tiene un marcador de posición. Reemplácelo por My First Outlook add-in.

5. Guarde el archivo.

   ...
   <ProviderName>John Doe</ProviderName>
   <DefaultLocale>en-US</DefaultLocale>
   <!-- The display name of your add-in. Used on the store and various places of the Office UI such as the add-ins dialog. -->
   <DisplayName DefaultValue="My Office Add-in" />
   <Description DefaultValue="My First Outlook add-in"/>
   ...
   

Pruébelo

1. Con Visual Studio, pruebe el complemento de Outlook recién creado presionando F5 o eligiendo el botón Inicio . El complemento se hospedará localmente en IIS.

2. En el cuadro de diálogo Conectarse a la cuenta de correo electrónico de Exchange , escriba la dirección de correo electrónico y la contraseña de su cuenta Microsoft y, a continuación, elija Conectar. Cuando se abre la página de inicio de sesión de Outlook.com en un explorador, inicie sesión en su cuenta de correo con las mismas credenciales que ha escrito anteriormente.

   Nota:

   Si el cuadro de diálogo Conectarse a la cuenta de correo electrónico de Exchange le pide repetidamente que inicie sesión o reciba un error que indica que no está autorizado, es posible que la autenticación básica esté desactivada para las cuentas de su inquilino de Microsoft 365. Para probar este complemento, intente iniciar sesión de nuevo después de establecer la propiedad Usar autenticación multifactor en True en la sección Implementación del cuadro de diálogo Propiedades del proyecto del complemento web o inicie sesión con una cuenta microsoft en su lugar.

3. El buzón se abre en Outlook en la Web. Seleccione o abra un mensaje.

   Sugerencia

   También puede probar el complemento en Outlook en Windows siempre y cuando se ejecute el servidor IIS.

4. En el mensaje, vaya a la barra de acciones y, a continuación, seleccione Aplicaciones.

   

5. En la lista de complementos, seleccione Mi complemento de Office y, a continuación, elija Mostrar panel de tareas.

   

6. Vea las propiedades del mensaje seleccionado en el panel de tareas que se abre.

   

   Nota:

   Si no se carga el panel de tareas, intente comprobarlo; para hacerlo, ábralo en un explorador en el mismo equipo.

Siguientes pasos

Enhorabuena, ha creado correctamente su primer complemento de Outlook. A continuación, obtenga más información sobre cómo Desarrollar complementos de Office con Visual Studio.

Solución de problemas

• Asegúrese de que el entorno está listo para el desarrollo de Office siguiendo las instrucciones de Configuración del entorno de desarrollo.

• Es posible que se produzca un error en el paso automático npm install que realiza Yo Office. Si ve errores al intentar ejecutar npm start, vaya a la carpeta del proyecto recién creada en un símbolo del sistema y ejecute npm installmanualmente . Para obtener más información sobre Yo Office, vea Crear proyectos de complementos de Office mediante el generador de Yeoman.

• Si el complemento muestra un error (por ejemplo, "No se pudo iniciar este complemento. Cierre este cuadro de diálogo para omitir el problema o haga clic en "Reiniciar" para volver a intentarlo. Al presionar F5 o elegir Depurar>iniciar depuración en Visual Studio, vea Depurar complementos de Office en Visual Studio para ver otras opciones de depuración.

• Parte del código de ejemplo usa ES6 JavaScript. Esto no es compatible con versiones anteriores de Office que usan el motor de explorador Trident (Internet Explorer 11). Para obtener información sobre cómo admitir esas plataformas en el complemento, consulte Compatibilidad con vistas web de Microsoft y versiones anteriores de Office. Si aún no tiene una suscripción a Microsoft 365 para usar para el desarrollo, puede calificar para una suscripción de desarrollador de Microsoft 365 E5 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.

Si recibe el error "No se puede abrir este complemento desde localhost" en el panel de tareas, siga los pasos descritos en el artículo de solución de problemas.

Ejemplos de código

• Complemento "Hello mundo" de Outlook: aprenda a crear un complemento de Office simple con solo un manifiesto, una página web HTML y un logotipo.

Consulte también

• Manifiesto XML de complementos de Office
• Uso de Visual Studio Code para publicar