Para usar la API de Documentos de Google de manera eficaz, debes comprender la arquitectura de un documento de Documentos de Google y los elementos que lo componen, así como la relación entre ellos. En esta página, se proporciona una descripción general detallada de estos temas:
- Un modelo conceptual de los elementos de los documentos
- Cómo la API de Documentos representa estos elementos
- Las propiedades de estilo de los elementos
Elementos de nivel superior
Los documentos son los elementos contenedores más externos de Documentos de Google. Esta es la unidad que se puede guardar en Google Drive, compartir con otros usuarios y actualizar con imágenes y texto.
Los elementos de nivel superior de un recurso documents incluyen Body, Header, Footer y muchos otros atributos:
document: {
body: ... ,
documentStyle: ... ,
lists: ... ,
documentId: ... ,
namedStyles: ... ,
revisionId: ... ,
title: ...
}
Para manipular funciones globales de documentos fuera del contenido de Body, casi siempre es mejor usar una o más plantillas de documentos, que puedes usar como base para generar documentos nuevos de manera programática. Para obtener más información, consulta Cómo combinar texto en un documento.
Contenido del cuerpo
Por lo general, Body incluye el contenido completo del documento. La mayoría de los elementos que puedes, o probablemente querrías, usar de manera programática son elementos dentro del contenido de Body:
Elemento estructural
Un StructuralElement describe el contenido que proporciona una estructura al documento. El contenido Body es una secuencia de objetos StructuralElement. Un elemento de contenido personaliza cada objeto StructuralElement, como se muestra en el siguiente diagrama:
Los elementos estructurales y sus objetos de contenido incluyen todos los componentes visuales dentro del documento. Esto incluye el texto, las imágenes intercaladas y el formato.
Estructura de párrafo
Un Paragraph es un StructuralElement que representa un párrafo. Tiene una variedad de contenido
que termina con un carácter de línea nueva. Se compone de los siguientes objetos:
ParagraphElement: Describe el contenido dentro de un párrafo.ParagraphStyle: Es un elemento opcional que establece de forma explícita las propiedades de diseño del párrafo.Bullet: Si el párrafo es parte de una lista, es un elemento opcional que proporciona la especificación de la viñeta.
El ParagraphElement funciona como un StructuralElement. Un conjunto de tipos de elementos de contenido (como ColumnBreak y Equation) personaliza su propio ParagraphElement, como se muestra en el siguiente diagrama:
Para ver un ejemplo de una estructura de documento completa, consulta el ejemplo de documento en formato JSON. En el resultado, puedes ver muchos de los elementos estructurales y de contenido clave, así como el uso de índices de inicio y fin, como se describe en la siguiente sección.
Ejecuciones de texto
Un TextRun es un ParagraphElement que representa una cadena contigua de texto con el mismo estilo de texto. Un párrafo puede contener varias ejecuciones de texto, pero las ejecuciones de este nunca cruzan los límites del párrafo. El contenido se divide después de un carácter de línea nueva para formar ejecuciones de texto independientes. Por ejemplo, considera un documento pequeño como el siguiente:
En el siguiente diagrama, se muestra cómo puedes visualizar la secuencia de párrafos del documento anterior, cada uno con su propia TextRun y la configuración opcional de Bullet.
AutoText
AutoText es un objeto ParagraphElement que representa un punto en el texto que se reemplaza de forma dinámica por contenido que puede cambiar con el tiempo. En Documentos, se usa para
los números de página.
Índices de inicio y finalización
Cuando actualizas el contenido de un documento, cada actualización ocurre en una ubicación o en un rango dentro del documento. Estas ubicaciones y rangos se especifican mediante índices, que representan un desplazamiento dentro de un segmento de documento contenedor. Un segmento es el cuerpo, el encabezado, el pie de página o la nota al pie que contiene elementos estructurales o de contenido. Los índices de los elementos dentro de un segmento son relativos al comienzo de ese segmento.
La mayoría de los elementos dentro del contenido del cuerpo tienen las propiedades startIndex y endIndex basadas en cero. Estos indican el desplazamiento del principio y el final de un elemento en relación con el comienzo del segmento que lo contiene. Si quieres obtener más información para ordenar las llamadas por lotes a la API de Documentos, consulta Actualizaciones por lotes.
Los índices se miden en unidades de código UTF-16. Esto significa que los pares subrogados consumen dos índices. Por ejemplo, el emoji "GRINNING FACE" (FRASCA) GRINNING, esto, se representa como \uD83D\uDE00 y consume dos índices.
En el caso de los elementos dentro del cuerpo de un documento, los índices representan desplazamientos desde el principio del contenido del cuerpo, que es el elemento “raíz”.
Los tipos de "personalización" de elementos estructurales (SectionBreak, TableOfContents, Table y Paragraph) no tienen estos índices porque su StructuralElement encerrado tiene estos campos. Lo mismo sucede con los tipos de personalización
que contiene una ParagraphElement, como TextRun, AutoText y
PageBreak.
Elementos de acceso
Muchos elementos se pueden modificar con el método documents.batchUpdate. Por ejemplo, con InsertTextRequest, puedes cambiar el contenido de cualquier elemento que tenga texto. De manera similar, puedes usar UpdateTextStyleRequest para aplicar formato a un rango de texto contenido en uno o más elementos.
Si quieres leer los elementos del documento, usa el método documents.get para obtener un volcado de JSON del documento completo. Luego, puedes analizar el JSON resultante para encontrar los valores de los elementos individuales. Para obtener más información, consulta Contenido del documento de salida como JSON.
El análisis del contenido puede ser beneficioso para diversos casos de uso. Considera, por ejemplo, una aplicación de catalogación de documentos que enumera los documentos que encuentra. Esta app puede extraer el título, el ID de revisión y el número de página de inicio de un documento, como se muestra en el siguiente diagrama:
Como no hay métodos para leer esta configuración de forma explícita, la app necesita obtener todo el documento y, luego, analizar el JSON para extraer estos valores.
Herencia de la propiedad
Un StructuralElement puede heredar propiedades de sus objetos superiores. Las propiedades de un objeto, incluidas las que define y hereda, determinan su aspecto visual final.
El formato de caracteres del texto determina cómo se renderiza el texto en un documento, por ejemplo, en negrita, cursiva y subrayado. El formato que aplicas anula el formato predeterminado heredado del TextStyle del párrafo subyacente. Por el contrario, los caracteres cuyo formato no establezcas continuarán heredando de los diseños del párrafo.
El formato de párrafo determina cómo se renderizan los bloques de texto en un documento, como la alineación, los bordes y la sangría. El formato que aplicas anula el formato predeterminado heredado del ParagraphStyle subyacente.
Por el contrario, cualquier componente de formato que no definas seguirá heredando el diseño de párrafo.