Compartir a través de

Inicio rápido: Compilación del primer complemento de panel de tareas Word con Visual Studio

En este inicio rápido, creará un complemento de panel de tareas Word que muestra cómo:

  • Insertar texto en diferentes ubicaciones de un documento (selección, principio, fin).
  • Use la API de JavaScript Word para manipular el contenido del documento.
  • Configurar un proyecto de Visual Studio para el desarrollo de complementos de Office.

Lo que va a compilar

Creará un complemento de panel de tareas sencillo pero funcional con tres botones que insertan comillas inspiradoras en un documento Word en posiciones diferentes. Este inicio rápido práctico le enseña los aspectos básicos de Word desarrollo de complementos.

Características clave que implementará

  • Insertar contenido en la selección actual.
  • Inserte contenido al principio del documento.
  • Inserte contenido al final del documento.
  • Controle las operaciones asincrónicas con la API de JavaScript de Word.

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.

Project Description
Proyecto de complemento Contiene solo un archivo de manifiesto de complemento con formato XML, que contiene toda la configuración que describe 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.

Paso 1: Actualizar el marcado HTML

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>

Paso 2: Agregar la funcionalidad de JavaScript

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));
            }
        });
    }
})();

Paso 3: Agregar estilo personalizado

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;
}

Paso 4: Actualizar el manifiesto del complemento

  1. Abra el archivo de manifiesto de solo complemento en el proyecto de 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.

    La aplicación Word con el botón Mostrar panel de tareas resaltado.

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

    La aplicación Word con el complemento reutilizable cargado.

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 Microsoft Edge DevTools, consulte Depuración de complementos mediante herramientas para desarrolladores en Microsoft Edge.

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

  • 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.

Ejemplos de código

Vea también

Conceptos básicos

Herramientas y referencia de API

Publicación e implementación

  • Last updated on