Ejercicio: Insertar y dar formato a un intervalo de texto

  • 17 minutos

En este ejercicio, creará un complemento de Word que inserta rangos de texto y párrafos y da formato a este texto.

Requisitos previos

El desarrollo de complementos de Office para Microsoft Word requiere Word 2016, versión 1711 (compilación 8730.1000 Hacer clic y ejecutar) o posterior. Puede que necesite ser participante de Office Insider para obtener esta versión. Para más información, vea Participar en Office Insider.

Usará Node.js para crear el complemento personalizado de Word en este módulo. En los ejercicios de este módulo se presupone que tiene las herramientas siguientes instaladas en su estación de trabajo del desarrollador.

Importante

En la mayoría de los casos, instalar la última versión de las siguientes herramientas es la mejor opción. Las versiones enumeradas aquí fueron usadas la última vez que se publicó y se probó este módulo.

Crear el proyecto de complemento

Ejecute el siguiente comando para crear un proyecto de complemento con el generador de Yeoman:

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:

  • Seleccionar un tipo de proyecto: Proyecto del panel de tareas del complemento de Office
  • Seleccionar un tipo de script: JavaScript
  • ¿Qué nombre quiere asignar al complemento? Mi complemento de Office
  • ¿Qué aplicación cliente de Office quiere admitir? Word

Captura de pantalla de las preguntas y respuestas del generador de Yeoman.

Después de completar el asistente, cambie a la carpeta del proyecto creada por el generador (Complemento de Mi Office) e instale los módulos npm mediante la ejecución de npm install.

Sugerencia

Al instalar dependencias, puede omitir las advertencias o errores que muestra el generador de Yeoman. El resto de esta unidad incluye todos los pasos que deberá seguir.

Insertar un rango de texto

En esta sección, comprobará mediante programación que el complemento es compatible con la versión actual de Word del usuario y, después, insertará un párrafo en el documento.

Programe el complemento

  1. Abra el proyecto en el editor de código.

  2. Abra el archivo ./src/taskpane/taskpane.html. El archivo contiene el formato HTML para el panel de tareas.

  3. Busque el elemento <main> y elimine todas las líneas que aparecen detrás de la etiqueta de apertura <main> y antes de la etiqueta de cierre </main>.

  4. Agregue el siguiente marcado inmediatamente después de la etiqueta de apertura <main>:

    <button class="ms-Button" id="insert-paragraph">Insert Paragraph</button><br/><br/>

  5. Abra el archivo ./src/taskpane/taskpane.js. Este archivo contiene el código de la API de JavaScript de Office que permite la interacción entre el panel de tareas y la aplicación host de Office.

  6. Para quitar todas las referencias al botón ejecutar y a la función run(), siga estos pasos:

    • Busque y elimine la línea document.getElementById("run").onclick = run;.
    • Encuentre y elimine la función run() completa.

  7. En la llamada al método Office.onReady(), busque la línea if (info.host === Office.HostType.Word) { y agregue el código siguiente inmediatamente después de esa línea:

    // Determine if the user's version of Office supports all the Office.js APIs that are used in the tutorial.
if (!Office.context.requirements.isSetSupported('WordApi', '1.3')) {
  console.log('Sorry. The tutorial add-in uses Word.js APIs that are not available in your version of Office.');
}

// Assign event handlers and other initialization logic.
document.getElementById("insert-paragraph").onclick = insertParagraph;

    Nota:

    • La primera parte de este código determina si la versión del usuario de Word admite una versión de Word.js que incluye todas las API usadas en este tutorial. En un complemento de producción, use el cuerpo del bloque condicional para ocultar o deshabilitar la interfaz de usuario que llama a las API no admitidas. Esto permitirá al usuario usar las partes del complemento compatibles con su versión de Word.
    • En la segunda parte de este código se agrega un controlador de eventos para el botón insert-paragraph.

  8. Agregue la siguiente función al final del archivo:

    async function insertParagraph() {
  await Word.run(async (context) => {

    // TODO1: Queue commands to insert a paragraph into the document.

    await context.sync();
  })
  .catch(function (error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
      console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
  });
}

    Nota:

    • La lógica de negocios de Word.js se agregará a la función que se pasa a Word.run. Esta lógica no se ejecuta inmediatamente. En su lugar, se agrega a una cola de comandos pendientes.
    • El método context.sync envía todos los comandos en cola a Word para su ejecución.
    • Word.run va seguido de un bloque catch. Este es el procedimiento recomendado que debe seguir siempre.

  9. En la función insertParagraph(), reemplace TODO1 con el código siguiente:

    const docBody = context.document.body;
docBody.insertParagraph("Office has several versions, including Office 2016, Microsoft 365 Click-to-Run, and Office on the web.",
                        "Start");

    Nota:

    • El primer parámetro del método insertParagraph es el texto del nuevo párrafo.
    • El segundo parámetro es la ubicación en el cuerpo donde se insertará el párrafo. Otras opciones para insertar un párrafo, si el objeto principal es el cuerpo, son "End" y "Replace".

  10. Guarde todos los cambios en los archivos taskpane.html y taskpane.js.

Probar el complemento

  1. Complete los pasos siguientes para iniciar el servidor web local y hacer una transferencia local del complemento:

    Nota:

    Los complementos de Office deben usar HTTPS y no HTTP, incluso cuando está desarrollando. Si le pedirá que instale un certificado después de ejecutar uno de los siguientes comandos, acepte la solicitud para instalar el certificado que proporciona el generador Yeoman.

    Sugerencia

    Si va a probar el complemento en macOS, ejecute el siguiente comando en el directorio raíz del proyecto 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 en Word en la web, ejecute el siguiente comando en el directorio raíz del proyecto. Al ejecutar este comando, se iniciará el servidor web local (si todavía no está en ejecución).

      npm run start:web

      Para usar el complemento, abra un nuevo documento en Word en la Web y, después, transfiera localmente el complemento siguiendo las instrucciones en Transferir localmente complementos de Office en Office en la Web.

  2. En Word, seleccione la pestaña Inicio y seleccione el botón Mostrar panel de tareas de la cinta de opciones para abrir el panel de tareas del complemento.

    Captura de pantalla de la aplicación Word con el botón Mostrar panel de tareas resaltado.

  3. En el panel de tareas, seleccione Insertar párrafo.

  4. Realice un cambio en el párrafo.

  5. Vuelva a seleccionar el botón Insertar párrafo. El nuevo párrafo aparece encima del anterior porque el método insertParagraph*() se inserta al principio del cuerpo del documento.

    Captura de pantalla del párrafo insertado por el tutorial en Word.

Dar formato al texto

En esta sección, aplicará un estilo integrado al texto, así como un estilo personalizado, y cambiará la fuente del texto.

Aplicar un estilo integrado al texto

  1. Abra el archivo ./src/taskpane/taskpane.html.

  2. Busque el elemento <button> para el botón insert-paragraph y agregue la siguiente revisión después de esa línea:

    <button class="ms-Button" id="apply-style">Apply Style</button><br/><br/>

  3. Abra el archivo ./src/taskpane/taskpane.js.

  4. En la llamada al método Office.onReady(), busque la línea siguiente en el método Office.onReady():

    document.getElementById("insert-paragraph").onclick = insertParagraph;

    Agregue el código siguiente inmediatamente después de esa línea:

    document.getElementById("apply-style").onclick = applyStyle;

  5. Agregue la siguiente función al final del archivo:

    async function applyStyle() {
  await Word.run(async (context) => {

    // TODO1: Queue commands to style text.

    await context.sync();
  })
  .catch(function (error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
      console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
  });
}

  6. En la función applyStyle(), reemplace TODO1 con el siguiente código. El código aplica un estilo a un párrafo, pero también puede aplicar estilos a rangos de texto.

    const firstParagraph = context.document.body.paragraphs.getFirst();
firstParagraph.styleBuiltIn = Word.Style.intenseReference;

Aplicar un estilo personalizado al texto

  1. Abra el archivo ./src/taskpane/taskpane.html.

  2. Busque el elemento <button> para el botón apply-style y agregue la siguiente revisión después de esa línea:

    <button class="ms-Button" id="apply-custom-style">Apply Custom Style</button><br/><br/>

  3. Abra el archivo ./src/taskpane/taskpane.js.

  4. En la llamada al método Office.onReady(), busque la línea siguiente en el método Office.onReady():

    document.getElementById("apply-style").onclick = applyStyle;

    Agregue el código siguiente inmediatamente después de esa línea:

    document.getElementById("apply-custom-style").onclick = applyCustomStyle;

  5. Agregue la siguiente función al final del archivo:

    async function applyCustomStyle() {
  await Word.run(async (context) => {

    // TODO1: Queue commands to apply the custom style.

    await context.sync();
  })
  .catch(function (error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
      console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
  });
}

  6. En la función applyCustomStyle(), reemplace TODO1 con el siguiente código. El código aplica un estilo personalizado que aún no existe. Creará un estilo con el nombre MyCustomStyle en un paso posterior.

    const lastParagraph = context.document.body.paragraphs.getLast();
lastParagraph.style = "MyCustomStyle";

  7. Compruebe que guardó todos los cambios que realizó en el proyecto.

Cambiar la fuente del texto

  1. Abra el archivo ./src/taskpane/taskpane.html.

  2. Busque el elemento <button> para el botón apply-custom-style y agregue la siguiente revisión después de esa línea:

    <button class="ms-Button" id="change-font">Change Font</button><br/><br/>

  3. Abra el archivo ./src/taskpane/taskpane.js.

  4. En la llamada al método Office.onReady(), busque la línea siguiente en el método Office.onReady():

    document.getElementById("apply-custom-style").onclick = applyCustomStyle;

    Agregue el código siguiente inmediatamente después de esa línea:

    document.getElementById("change-font").onclick = changeFont;

  5. Agregue la siguiente función al final del archivo:

    async function changeFont() {
  await Word.run(async (context) => {

    // TODO1: Queue commands to apply a different font.

    await context.sync();
  })
  .catch(function (error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
      console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
  });
}

  6. En la función changeFont(), reemplace TODO1 con el siguiente código. El código recibe una referencia al segundo párrafo mediante el método ParagraphCollection.getFirst() encadenado al método Paragraph.getNext().

    const secondParagraph = context.document.body.paragraphs.getFirst().getNext();
secondParagraph.font.set({
  name: "Courier New",
  bold: true,
  size: 18
});

  7. Compruebe que guardó todos los cambios que realizó en el proyecto.

Probar el complemento

  1. Si el servidor web local ya se está ejecutando y el complemento ya está cargado en Word, continúe con el paso 2. Si no, inicie el servidor web local y transfiera localmente el complemento:

    • 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 en Word en la web, ejecute el siguiente comando en el directorio raíz del proyecto. Al ejecutar este comando, se iniciará el servidor web local (si todavía no está en ejecución).

      npm run start:web

      Para usar el complemento, abra un nuevo documento en Word en la Web y, después, transfiera localmente el complemento siguiendo las instrucciones en Transferir localmente complementos de Office en Office en la Web.

  2. Si el panel de tareas del complemento aún no está abierto en Word, vaya a la pestaña Inicio y seleccione Mostrar panel de tareas.

  3. Asegúrese de que hay al menos tres párrafos en el documento. Puede elegir el botón Insertar párrafo tres veces. Compruebe cuidadosamente que no hay ningún párrafo en blanco al final del documento. Si lo hay, elimínelo.

  4. En Word, cree un estilo personalizado denominado MyCustomStyle. Puede tener el formato que quiera.

  5. Seleccione el botón Aplicar estilo. Al primer párrafo se le aplicará el estilo integrado Referencia intensa.

  6. Seleccione el botón Aplicar estilo personalizado. Al último párrafo se le aplicará el estilo personalizado. (Si no ocurre nada, el último párrafo podría estar en blanco. Si es así, agréguele texto).

  7. Seleccione el botón Cambiar fuente. La fuente del segundo párrafo cambia a 18 puntos, negrita, Courier New.

    Captura de pantalla de los estilos aplicados y la fuente cambiada por tutorial en Word.

Resumen

En este ejercicio, ha creado un complemento de Word que inserta rangos de texto y párrafos y da formato a ese texto.

Comprobar sus conocimientos

1.

¿Cómo se obtiene una instancia del contexto de Word actual de la API de JavaScript de Word?

2.

¿Cómo puede un complemento detectar la versión de la API de JavaScript de Word admitida en el componente actual?