En esta guía, se describe la estructura interna de un documento de Documentos de Google: los elementos que conforman un documento y la relación entre ellos.
Elementos de nivel superior
Los elementos de nivel superior de un documento incluyen el cuerpo y varios otros atributos del documento en su totalidad:
document: {
body: ... ,
documentStyle: ... ,
lists: ... ,
documentId: ... ,
namedStyles: ... ,
revisionId: ... ,
title: ...
}
Para manipular atributos globales de documentos fuera del contenido del cuerpo, 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.
Contenido del cuerpo
La mayoría de los elementos que puedes o quieres usar de manera programática son elementos dentro del contenido del cuerpo:
Elementos estructurales
El contenido del cuerpo es solo 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 todo el texto del documento, imágenes intercaladas, etcétera.
Los párrafos contienen un tipo especial de elemento llamado ParagraphElement que funciona de manera similar a StructuralElement. Un conjunto de tipos de elementos de contenido personaliza su propio ParagraphElement, como se muestra en el siguiente diagrama:
Para ver un ejemplo de una estructura de documento completa, consulta el volcado de muestra de un 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 finalización, como se describe en la siguiente sección.
Índice de inicio y finalización
La mayoría de los elementos dentro del contenido del cuerpo tienen las propiedades startIndex y endIndex. Indican el desplazamiento del principio y del final de un elemento en relación con el comienzo del segmento que lo contiene.
Los índices se miden en unidades de código UTF-16. Esto significa que los pares subrogados consumen 2 índices. Por ejemplo, el emoji de “CARA DE MUESTRA”, EST, se representará como “\uD83D\uDE00” y consumiría 2 í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" para elementos estructurales (SectionBreak, TableOfContents, Table y Paragraph) no tienen estos índices porque su StructuralElement contenedor tiene estos campos. Esto también se aplica a los tipos de personalización contenidos en un
ParagraphElement.
Estructura de párrafo
Un párrafo se compone de lo siguiente:
elements: Es una secuencia que contiene una o más instancias detextRun.paragraphStyle: Es un elemento opcional que establece de forma explícita las propiedades de estilo del párrafo.bullet: Es un elemento opcional que proporciona la especificación de la viñeta si el párrafo es parte de una lista.
Ejecuciones de texto
Una textRun representa una string contigua de texto con el mismo estilo de texto. Un párrafo puede contener varias ejecuciones de texto, pero estas no pueden cruzar sus límites. Considera, por ejemplo, un documento pequeño como el siguiente:
En el siguiente diagrama, se muestra cómo visualizar la secuencia de párrafos del documento anterior, cada uno con sus propias ejecuciones de texto y configuración de viñetas opcional.
Cómo acceder a los elementos
Muchos elementos se pueden modificar con el método BatchUpdate. Por ejemplo, mediante el tipo de solicitud InsertTextRequest, puedes modificar el contenido de cualquier elemento que contenga texto. De manera similar, puedes usar UpdateTextStyleRequest para aplicar formato a un rango de texto contenido en uno o más elementos.
Para leer elementos del documento, usa el método get a fin de obtener un volcado de JSON del documento completo. (Para conocer una manera de hacerlo, consulta la muestra Contenido del documento de salida como JSON). Luego, puedes analizar el JSON resultante para encontrar los valores de los elementos individuales.
El análisis del contenido puede ser útil para varios casos de uso. Considera, por ejemplo, una app de catalogación de documentos que enumera los documentos que encuentra. Esta app podría 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, tu app necesita obtener todo el documento y, luego, analizar el JSON para extraer estos valores.