Estrutura de um arquivo do Documentos Google

Este guia descreve a estrutura interna de um arquivo do Documentos Google: os elementos que compõem um arquivo e a relação entre eles.

Elementos de nível superior

Os elementos de nível superior de um documento incluem o corpo e vários outros atributos do documento como um todo:

document: {
    body: ... ,
    documentStyle: ... ,
    lists: ... ,
    documentId: ... ,
    namedStyles: ... ,
    revisionId: ... ,
    title: ...
}

Para manipular recursos globais de documentos fora do conteúdo do corpo, é quase sempre melhor usar um ou mais modelos de documento, que podem ser usados como base para gerar novos documentos de maneira programática.

Conteúdo do corpo

A maioria dos itens que você pode ou provavelmente vai querer usar de maneira programática são elementos do conteúdo do corpo:

Elementos estruturais

O conteúdo do corpo é apenas uma sequência de objetos StructuralElement. Um elemento de conteúdo personaliza cada objeto StructuralElement, conforme mostrado no diagrama a seguir:

Os elementos estruturais e os objetos de conteúdo deles contêm todo o texto do documento, imagens inline e assim por diante.

Os parágrafos contêm um tipo especial de elemento conhecido como ParagraphElement, que funciona como um StructuralElement. Um conjunto de tipos de elementos de conteúdo personaliza o próprio ParagraphElement, como mostrado no diagrama a seguir:

Para ver um exemplo de estrutura completa de documento, consulte o despejo de amostra de um documento no formato JSON. Na saída, é possível ver muitos dos principais elementos estruturais e de conteúdo, bem como o uso de índices inicial e final, conforme descrito na seção a seguir.

Índice inicial e final

A maioria dos elementos no conteúdo do corpo tem as propriedades startIndex e endIndex. Eles indicam o deslocamento do início e do fim de um elemento em relação ao início do segmento incluído.

Os índices são medidos em unidades de código UTF-16. Isso significa que os pares substitutos consomem dois índices. Por exemplo, o emoji "GRINNING FACE", maneira, seria representado como "\uD83D\uDE00" e consumiria dois índices.

Para elementos no corpo de um documento, os índices representam deslocamentos desde o início do conteúdo do corpo, que é o elemento "raiz".

Os tipos de "personalização" para elementos estruturais (SectionBreak, TableOfContents, Table e Paragraph) não têm esses índices porque o anexo StructuralElement tem esses campos. Isso também vale para os tipos de personalização contidos em um ParagraphElement.

Estrutura do parágrafo

Um parágrafo é composto pelo seguinte:

• elements: uma sequência que contém uma ou mais instâncias de textRun.
• paragraphStyle: um elemento opcional que define explicitamente as propriedades de estilo do parágrafo.
• bullet: um elemento opcional que fornece a especificação do marcador se o parágrafo fizer parte de uma lista.

Execuções de texto

Um textRun representa uma string contígua de texto com o mesmo estilo de texto. Um parágrafo pode conter várias execuções de texto, mas elas não podem cruzar os limites de parágrafo. Considere, por exemplo, um documento pequeno como este:

O diagrama a seguir mostra como visualizar a sequência de parágrafos no documento acima, cada um com suas próprias execuções de texto e configurações de marcadores opcionais.

Acessar elementos

Muitos elementos podem ser modificados usando o método BatchUpdate. Por exemplo, ao usar o tipo de solicitação InsertTextRequest, é possível modificar o conteúdo de qualquer elemento que contenha texto. Da mesma forma, é possível usar UpdateTextStyleRequest para aplicar formatação a um intervalo de texto contido em um ou mais elementos.

Para ler elementos do documento, use o método get para receber um despejo JSON do documento completo. Para saber como fazer isso, consulte o exemplo Conteúdo do documento de saída como JSON. Em seguida, analise o JSON resultante para encontrar os valores de elementos individuais.

A análise do conteúdo pode ser útil para vários casos de uso. Considere, por exemplo, um documento que cataloga os documentos que lista os apps que ele encontra. Esse app pode extrair o título, o ID da revisão e o número da página inicial de um documento, conforme mostrado no diagrama a seguir:

Como não há métodos para ler essas configurações explicitamente, seu app precisa extrair o documento inteiro e analisar o JSON para extrair esses valores.