Crear el primer complemento de panel de tareas de Word

Este artículo le guiará a través del proceso de creación de un complemento de panel de tareas de Word.

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.

Creación del proyecto de complemento

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
• ¿Cómo desea asignarle el nombre al complemento?My Office Add-in
• ¿Qué aplicación cliente de Office le gustaría admitir?Word

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.

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 básico. Si quiere explorar los componentes del proyecto de complemento, abra el proyecto en el editor de código y revise los archivos que se enumeran a continuación. Cuando esté listo para probar el complemento, vaya a la sección siguiente.

• 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 la aplicación cliente de Office.

Pruébelo

1. Navegue hasta la carpeta raíz del proyecto.

   cd "My Office Add-in"
   

2. Complete los pasos siguientes para iniciar el servidor web local y transferir localmente el complemento.

   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.

   Sugerencia

   Si está probando el complemento en Mac, ejecute el siguiente comando antes de continuar. Al ejecutar este comando, se iniciará el servidor web local.

   npm run dev-server
   

   • Para probar el complemento en Word, ejecute el siguiente comando en el directorio raíz del proyecto. Se iniciará el servidor web local (si todavía no está en ejecución) y se abrirá Word con el complemento cargado.

     npm start
     

   • Para probar el complemento de Word en un explorador, ejecute el siguiente comando en el directorio raíz del proyecto. Al ejecutar este comando, se iniciará el servidor web local. Reemplace "{url}" por la dirección URL de un documento de Word en OneDrive o en una biblioteca de SharePoint para la que tenga permisos.

     Nota:

     Si va a desarrollar en un Equipo Mac, incluya entre {url} comillas simples. No haga esto en Windows.

     npm run start:web -- --document {url}
     

     Estos son algunos ejemplos.

     • npm run start:web -- --document https://contoso.sharepoint.com/:t:/g/EZGxP7ksiE5DuxvY638G798BpuhwluxCMfF1WZQj3VYhYQ?e=F4QM1R
     • npm run start:web -- --document https://1drv.ms/x/s!jkcH7spkM4EGgcZUgqthk4IK3NOypVw?e=Z6G1qp
     • npm run start:web -- --document https://contoso-my.sharepoint-df.com/:t:/p/user/EQda453DNTpFnl1bFPhOVR0BwlrzetbXvnaRYii2lDr_oQ?e=RSccmNP

     Si el complemento no se carga localmente en el documento, desinstalándolo manualmente siguiendo las instrucciones de Instalación local manual de complementos en Office en la Web.

3. En Word, si el panel de tareas "Mi complemento de Office" aún no está abierto, abra un nuevo documento, elija la pestaña Inicio y, a continuación, elija el botón Mostrar panel de tareas en la cinta de opciones para abrir el panel de tareas del complemento.

   

4. En la parte inferior del panel de tareas seleccione el vínculo Ejecutar para agregar el texto «Hola, mundo» al documento en una fuente azul.

   

Siguientes pasos

Enhorabuena, ha creado correctamente un complemento de panel de tareas de Word. Ahora, obtenga más información sobre las funcionalidades de un complemento de Word y cree un complemento más complejo siguiendo este tutorial de complementos de Word.

Tutorial de complemento de Word

Visual Studio

Requisitos previos

• Visual Studio 2019 o posterior con la carga de trabajo de Desarrollo de Office y SharePoint ya instalada.

  Nota:

  Si ya ha instalado Visual Studio, use el Instalador de Visual Studio para asegurarse de que la carga de trabajo Desarrollo de Office y SharePoint esté instalada.

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

Creación del proyecto de complemento

1. En Visual Studio, seleccione Crear un nuevo proyecto.

2. Utilizando el cuadro de búsqueda, escribacomplemento. Seleccioneun complemento de Web de Word,y a continuación, seleccioneSiguiente.

3. Asigne un nombre al proyecto y seleccioneCrear.

4. Visual Studio crea una solución, y los dos proyectos que contiene aparecen en el Explorador de soluciones. El archivo Home.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. Cambie 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 su complemento, Visual Studio aloja la aplicación web en su servidor local 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. Home.html especifica el código HTML que se representará en el panel de tareas del complemento. En Home.html, reemplace el elemento <body> por la marcación siguiente y guarde el archivo.

   <body>
       <div id="content-header">
           <div class="padding">
               <h1>Welcome</h1>
           </div>
       </div>
       <div id="content-main">
           <div class="padding">
               <p>Choose the buttons below to add boilerplate text to the document by using the Word JavaScript API.</p>
               <br />
               <h3>Try it out</h3>
               <button id="emerson">Add quote from Ralph Waldo Emerson</button>
               <br /><br />
               <button id="checkhov">Add quote from Anton Chekhov</button>
               <br /><br />
               <button id="proverb">Add Chinese proverb</button>
           </div>
       </div>
       <br />
       <div id="supportedVersion"/>
   </body>
   

2. Abra el archivo Home.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.
               // Use this to check whether the API is supported in the Word client.
               if (Office.context.requirements.isSetSupported('WordApi', '1.1')) {
                   // Do something that is only available via the new APIs.
                   $('#emerson').on("click", insertEmersonQuoteAtSelection);
                   $('#checkhov').on("click", insertChekhovQuoteAtTheBeginning);
                   $('#proverb').on("click", insertChineseProverbAtTheEnd);
                   $('#supportedVersion').html('This code is using Word 2016 or later.');
               } else {
                   // Lets you know that this code will not work with your version of Word.
                   $('#supportedVersion').html('This code requires Word 2016 or later.');
               }
           });
       });
   
       async function insertEmersonQuoteAtSelection() {
           await Word.run(async (context) => {
   
               // Create a proxy object for the document.
               const thisDocument = context.document;
   
               // Queue a command to get the current selection.
               // Create a proxy range object for the selection.
               const range = thisDocument.getSelection();
   
               // Queue a command to replace the selected text.
               range.insertText('"Hitch your wagon to a star." - Ralph Waldo Emerson\n', Word.InsertLocation.replace);
   
               // Synchronize the document state by executing the queued commands,
               // and return a promise to indicate task completion.
               await context.sync();
               console.log('Added a quote from Ralph Waldo Emerson.');
           })
           .catch(function (error) {
               console.log('Error: ' + JSON.stringify(error));
               if (error instanceof OfficeExtension.Error) {
                   console.log('Debug info: ' + JSON.stringify(error.debugInfo));
               }
           });
       }
   
       async function insertChekhovQuoteAtTheBeginning() {
           await Word.run(async (context) => {
   
               // Create a proxy object for the document body.
               const body = context.document.body;
   
               // Queue a command to insert text at the start of the document body.
               body.insertText('"Knowledge is of no value unless you put it into practice." - Anton Chekhov\n', Word.InsertLocation.start);
   
               // Synchronize the document state by executing the queued commands,
               // and return a promise to indicate task completion.
               await context.sync();
               console.log('Added a quote from Anton Chekhov.');
           })
           .catch(function (error) {
               console.log('Error: ' + JSON.stringify(error));
               if (error instanceof OfficeExtension.Error) {
                   console.log('Debug info: ' + JSON.stringify(error.debugInfo));
               }
           });
       }
   
       async function insertChineseProverbAtTheEnd() {
           await Word.run(async (context) => {
   
               // Create a proxy object for the document body.
               const body = context.document.body;
   
               // Queue a command to insert text at the end of the document body.
               body.insertText('"To know the road ahead, ask those coming back." - Chinese proverb\n', Word.InsertLocation.end);
   
               // Synchronize the document state by executing the queued commands,
               // and return a promise to indicate task completion.
               await context.sync();
               console.log('Added a quote from a Chinese proverb.');
           })
           .catch(function (error) {
               console.log('Error: ' + JSON.stringify(error));
               if (error instanceof OfficeExtension.Error) {
                   console.log('Debug info: ' + JSON.stringify(error.debugInfo));
               }
           });
       }
   })();
   

3. Abra el archivo Home.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.

   #content-header {
       background: #2a8dd4;
       color: #fff;
       position: absolute;
       top: 0;
       left: 0;
       width: 100%;
       height: 80px;
       overflow: hidden;
   }
   
   #content-main {
       background: #fff;
       position: fixed;
       top: 80px;
       left: 0;
       right: 0;
       bottom: 0;
       overflow: auto;
   }
   
   .padding {
       padding: 15px;
   }
   

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 con Mi complemento de Office.

4. El atributo DefaultValue del elemento Description tiene un marcador de posición. Reemplácelo con Un complemento de panel de tareas para Word.

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-in's dialog. -->
   <DisplayName DefaultValue="My Office Add-in" />
   <Description DefaultValue="A task pane add-in for Word."/>
   ...
   

Pruébelo

1. Con Visual Studio, pruebe el complemento de Word recién creado presionando F5 o eligiendo Depurar>Iniciar depuración para iniciar Word con el botón Mostrar complemento panel de tareas que se muestra en la cinta de opciones. El complemento se hospedará localmente en IIS.

2. En Word, si el panel de tareas del complemento aún no está abierto, elija la pestaña Inicio 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. (Si usa una versión perpetua con licencia por volumen de Office 2016 o anterior, no se admiten botones personalizados. En su lugar, el panel de tareas se abrirá inmediatamente).

   

3. En el panel de tareas elija cualquiera de los botones para agregar texto reutilizable al documento.

   

Nota:

Para ver los resultados del console.log, necesitará un conjunto de herramientas de desarrollo independiente para una consola JavaScript. Para obtener más información sobre las herramientas F12 y el Microsoft Edge DevTools, visite Complementos de depuración con herramientas de desarrollo para Internet Explorer, Complementos de depuración con herramientas para desarrolladores para Edge (versión heredada) o Complementos de depuración con herramientas para desarrolladores en Microsoft Edge (basado en Chromium).

Siguientes pasos

Enhorabuena, ha creado correctamente un complemento de panel de tareas de Word. A continuación, para obtener más información sobre el desarrollo de complementos de Office con Visual Studio, continúe con el siguiente artículo.

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.

Ejemplos de código

• Word complemento "Hello mundo": obtenga información sobre cómo crear un complemento de Office simple con solo un manifiesto, una página web HTML y un logotipo.

Vea también

• Información general sobre la plataforma de complementos de Office
• Desarrollo de complementos de Office
• Información general sobre los complementos de Word
• Ejemplos de código de complementos de Word
• Referencia de la API de JavaScript de Word
• Uso de Visual Studio Code para publicar