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 como un todo:
document: {
body: ... ,
documentStyle: ... ,
lists: ... ,
documentId: ... ,
namedStyles: ... ,
revisionId: ... ,
title: ...
}
Para manipular las funciones del documento globales fuera del contenido del cuerpo, casi siempre es mejor usar una o más plantillas de documento, que puedes usar como base para generar documentos nuevos de manera programática.
Contenido del cuerpo
La mayoría de los elementos que puedes usar, o que probablemente quieras, 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, por ejemplo, como 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 los índices de inicio y finalización, como se describe en la siguiente sección.
Índice de inicio y fin
La mayoría de los elementos dentro del contenido del cuerpo tienen las propiedades startIndex y endIndex. Indican el desplazamiento del comienzo y el final de un elemento en relación con el comienzo de su segmento envolvente.
Los índices se miden en unidades de código UTF-16. Esto significa que los pares subrogados consumen 2 índices. Por ejemplo, el emoji “GRINNING FACE”, CPD, se representaría como “\uD83D\uDE00” y consumiría 2 índices.
Para los elementos dentro de un cuerpo de documento, los índices representan desplazamientos desde el comienzo 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 entorno StructuralElement tiene estos campos. Esto también se aplica a los tipos de personalización que contiene 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 configura 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 forma parte de una lista.
Ejecuciones de texto
Un objeto 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 los límites del párrafo. Por ejemplo, considera un documento pequeño como el siguiente:
En el siguiente diagrama, se muestra cómo visualizar la secuencia de párrafos en el documento anterior, cada una con sus propias ejecuciones de texto y configuración opcional de viñetas.
Cómo acceder a los elementos
Muchos elementos se pueden modificar con el método BatchUpdate. Por ejemplo, con 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 obtener una manera de hacerlo, consulta el ejemplo Contenido de documentos de salida como JSON). Luego, puedes analizar el JSON resultante para encontrar los valores de los elementos individuales.
Analizar el contenido puede ser útil para varios casos de uso. Considera, por ejemplo, un documento que cataloga una app que cataloga 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 estas configuraciones de forma explícita, tu app debe obtener el documento completo y, luego, analizar el JSON a fin de extraer estos valores.