Trabajar con texto, formato, selecciones e intervalos en documentos de Word

  • 14 minutos

La API de JavaScript de Word permite el control mediante programación sobre texto, formato, selecciones e intervalos en documentos de Word. En esta unidad, aprenderá a trabajar con texto o párrafos, a aplicar estilos y formato al texto, y a trabajar con selecciones e intervalos de texto de un complemento personalizado de Word.

Introducción a la plataforma para desarrolladores de Office

La plataforma para desarrolladores de Microsoft 365, que incluye Office, ofrece muchos lienzos para que los desarrolladores inserten personalizaciones y los complementos de Office son uno de los tres lienzos: documentos, conversaciones y páginas.

Microsoft Teams posibilita conversaciones entre los usuarios y permite a los desarrolladores ampliar la experiencia mediante extensiones de mensajería, bots de conversación y otras opciones de personalización.

Los desarrolladores personalizan páginas en SharePoint Server y SharePoint Online con SharePoint Framework.

Los clientes de Office, como Word, Excel, PowerPoint, OneNote y Outlook también se pueden ampliar para implementar paneles de tareas personalizados, acciones y otras personalizaciones mediante complementos.

Diagrama de información general de la plataforma Microsoft 365.

Anatomía del complemento Office.js para Microsoft Word

Comenzaremos examinando una anatomía de Office.js para Microsoft Word:

Esquema de la anatomía de un complemento de Office.js.

  • Todos los complementos de Office deben desactivar el método Office.initialize() cuando una página carga por primera vez el complemento.
  • Si usa una funcionalidad de Office.js más reciente en el complemento, es importante comprobar si el cliente admite esas extensiones mediante la API de requirements.
  • Para las API de JavaScript de Word, usará el método Word.run() para obtener una instancia del documento actual context.
  • Una vez que tenga una referencia al context del documento de Word actual, puede cargar cualquier propiedad en el contexto mediante el método load(). Este método agregará la cola de solicitudes, lo que le permite encadenar varias solicitudes por motivos de rendimiento.
  • Cuando esté listo para recuperar las propiedades que ha puesto en cola o para realizar cualquier acción en cola, use el método context.sync() para ejecutar el lote de operaciones en cola definidas mediante el método load().
  • El método context.sync() devuelve una promesa de JavaScript que se puede usar para obtener resultados o una operación anterior y realizar nuevas operaciones.
  • Como procedimiento recomendado, debe escuchar, detectar y controlar los errores que puedan producirse al trabajar con las API de JavaScript de Word.

Texto y párrafos

Los desarrolladores de complementos de Word deben comprender la jerarquía de un documento de Word y cómo se relaciona con los objetos de Office.js.

Diagrama que muestra la jerarquía de documentos de Word.

Office.js proporciona contexto a un documento de Word a través de Word.run y la propiedad context.document. El documento contiene un cuerpo, que contiene muchas colecciones, incluidos párrafos, tablas y mucho más.

Las relaciones de esta jerarquía se exponen como propiedades en la API que permiten el recorrido hacia arriba (por ejemplo, paragraph.parentBody), hacia abajo (por ejemplo, body.paragraphs) y horizontal (por ejemplo, paragraph.getNext() o paragraph.getPrevious()).

Office.js le permite insertar nuevos párrafos y editar, eliminar o borrar párrafos existentes y cómo aparecen en un documento.

Los párrafos son conscientes de sus elementos relacionados mediante operaciones de getNext() y getPrevious() y al insertar un párrafo relativo a sí mismos mediante la ubicación before de after.

Los fragmentos de código siguientes muestran ejemplos de trabajo de texto y párrafos de trabajo con la API de JavaScript de Word:

  • obtener referencia al cuerpo del documento:

    const docBody = context.document.body;

  • insertar un párrafo al principio del cuerpo del documento:

    docBody.insertParagraph('Hello World', 'Start');

  • obtener una referencia al primer párrafo en el cuerpo de un documento:

    const paragraph = context.document.body.paragraphs.getFirst();

  • obtener una referencia al segundo párrafo en el cuerpo de un documento:

    const paragraph = context.document.body.paragraphs.getFirst().getNext();

  • obtener una referencia al último párrafo en el cuerpo de un documento:

    const paragraph = context.document.body.paragraphs.getLast();

  • insertar un párrafo después de la ubicación del párrafo actual:

    paragraph.insertParagraph('Hello World', 'After');

  • borrar el contenido de un párrafo:

    paragraph.clear();

  • eliminar el primer párrafo de un documento:

    const paragraph = context.document.body.paragraphs.items[0].delete();

  • insertar un salto de página después de un párrafo:

    paragraph.insertBreak('page', 'After');

  • iterar por todos los párrafos de un documento:

    const paragraphs = context.document.body.paragraphs;
context.load(paragraphs, 'text');
return context.sync().then(() => {
  for (let i = 0; i < paragraphs.items.length; i++) {
    // do something with paragraph (paragraphs.items[i])
  }
}).then(context.sync);

Estilos y formato de texto

Los estilos y el formato son lo que hace que un documento sea atractivo. Office.js le permite trabajar fácilmente con estilos y formatos de su complemento personalizado de Word.

Captura de pantalla de estilos y controles de formato en la cinta de opciones de Word.

Estilos

Los estilos de Microsoft Word son similares a una clase CSS en HTML. Proporcionan un conjunto preconfigurado y reutilizable de formato que se aplicará a un párrafo o rango de texto.

Office.js puede aplicar estilos predeterminados y estilos personalizados a párrafos e intervalos de texto.

Fuentes

Modificar una fuente es similar a aplicar un estilo insertado en HTML. Establecer una fuente le permite manipular la familia de fuentes, el peso, el tamaño, los colores y mucho más.

Al igual que los estilos, las fuentes se pueden aplicar a un párrafo o rango de texto completo.

Formato de párrafo

Además de los estilos y las fuentes, los párrafos ofrecen más formato a través de Office.js, como la alineación, la sangría y el interlineado.

Los fragmentos de código siguientes muestran ejemplos de trabajo de aplicación de estilos y formato a texto y párrafos mediante la API de JavaScript de Word:

  • aplicar un estilo de Word conocido a un párrafo:

    paragraph.styleBuiltIn = Word.Style.intenseReference;

  • aplicar un estilo personalizado a un párrafo:

    paragraph.style = 'MyCustomStyle';

  • establecer la propiedad de alineación de párrafo mediante left, centered, right o justified:

    paragraph.alignment = 'centered';

  • cambiar la fuente de un rango de texto:

    range.font.set({
    name: 'Courier New',
    bold: true,
    size: 18,
    color: '#0000ff',
    highlightColor: '#ffff00'
});

Selecciones y rangos

Al trabajar con complementos de Office, los desarrolladores a menudo escucharán el término rango. Un rango es cualquier área contigua de un documento en Microsoft Word.

Los rango se pueden establecer de muchas maneras, como la búsqueda, la selección o una conversión. Por ejemplo, el método paragraph.getRange() devolverá el párrafo como un rango.

Captura de pantalla de Microsoft Word con texto seleccionado.

Las selecciones permiten manipular el contenido y la ubicación del foco en un documento.

Puede obtener la selección de un rango o establecer la selección en un rango.

Los fragmentos de código siguientes muestran ejemplos de trabajo de obtención y trabajo con selecciones de texto mediante la API de JavaScript de Word:

  • obtener un rango de texto seleccionado:

    const originalRange = document.getSelection();

  • anexar texto a un rango de texto:

    originalRange.insertText('added to the end', 'End');

  • seleccionar un rango de texto mediante los modos de sección de Select, Start o End:

    someRange.select('Select');

  • buscar en el párrafo actual un rango de texto y reemplazarlo:

    const ranges = paragraph.search('office', {matchCase: true, ignoreSpace: true});
context.load(ranges);
return context.sync().then(() => {
  for (let i = 0; i < ranges.items.length; i++) {
    ranges.items[i].insertText("Office", "Replace");
  }
}).then(context.sync);

Resumen

La API de JavaScript de Word permite el control mediante programación sobre texto, formato, selecciones e intervalos en documentos de Word. En esta unidad, aprenderá a trabajar con texto, párrafos, aplicar estilos y formato al texto, y a trabajar con selecciones e intervalos de texto de un complemento personalizado de Word.