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 del documento
- Cómo la API de Documentos representa estos elementos
- Las propiedades de diseño de los elementos
Elementos de nivel superior
El elemento contenedor más externo de Documentos de Google es un documento. 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 las funciones de documentos globales 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 Combina 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 que podrías querer usar de manera programática son elementos dentro del contenido de Body:
Elemento estructural
Un objeto StructuralElement describe el contenido que proporciona 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 contienen todos los componentes visuales dentro del documento. Esto incluye el texto, las imágenes intercaladas y el formato.
Estructura del párrafo
Un objeto Paragraph es un objeto 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 de un párrafo.ParagraphStyle: Es un elemento opcional que establece de manera explícita las propiedades de estilo del párrafo.Bullet: Si el párrafo es parte de una lista, es un elemento opcional que proporciona la especificación de viñeta.
ParagraphElement funciona de forma similar a 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, además del uso de los índices de inicio y fin, como se describe en la siguiente sección.
Ejecuciones de texto
Una TextRun es una ParagraphElement que representa una cadena contigua de texto con el mismo estilo. Un párrafo puede contener varias ejecuciones de texto, pero estas nunca cruzan sus límites. El contenido se divide después de un carácter de línea nueva para formar ejecuciones de texto separadas. 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 propio TextRun y su configuración opcional Bullet.
AutoText
AutoText es un ParagraphElement que representa un lugar 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 se realiza en una ubicación o dentro de un rango del documento. Estas ubicaciones y estos rangos se especifican con índices, que representan un desplazamiento dentro de un segmento del 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 se relacionan con el 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 encierra. Si quieres obtener más información para ordenar las llamadas a la API de Documentos por lotes, 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", pic_antes, se representa como \uD83D\uDE00 y consume dos índices.
Para los elementos dentro del cuerpo de un documento, los índices representan los desplazamientos desde el principio del contenido del cuerpo, que es el elemento “raíz”.
Los tipos de "personalización" para los elementos
estructurales (SectionBreak,
TableOfContents,
Table y
Paragraph) no tienen estos índices porque la StructuralElement delimitante tiene estos campos. Esto también se aplica a los tipos de personalización
que se incluyen en un ParagraphElement, como TextRun, AutoText y
PageBreak.
Accede a los elementos
Muchos elementos se pueden modificar con el método documents.batchUpdate. Por ejemplo, con InsertTextRequest, puedes cambiar el contenido de cualquier elemento que incluya texto. De manera similar, puedes usar UpdateTextStyleRequest para aplicar formato a un rango de texto contenido en uno o más elementos.
Para leer los elementos del documento, usa el método documents.get a fin de obtener un volcado de JSON del documento completo. Luego, puedes analizar el JSON resultante para encontrar los valores de elementos individuales. Para obtener más información, consulta Contenido del documento de salida en formato JSON.
Analizar el contenido puede ser beneficioso para varios 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 de texto determina cómo se renderiza el texto en un documento, como negrita, cursiva y subrayado. El formato que apliques anula el formato predeterminado heredado del TextStyle del párrafo subyacente. Por el contrario, los caracteres cuyo formato no configures se seguirán heredando de los estilos 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 las sangrías. El formato que apliques anula el formato predeterminado heredado del ParagraphStyle subyacente.
Por el contrario, cualquier función de formato que no configures se seguirá heredando del estilo de párrafo.