Estrutura de um arquivo do Documentos Google

Para usar a API Google Docs de maneira eficaz, você precisa entender a arquitetura de um documento do Google Docs e os elementos que compõem um documento, bem como a relação entre eles. Nesta página, você encontra uma visão geral detalhada desses tópicos:

• Um modelo conceitual dos elementos do documento
• Como a API Docs representa esses elementos
• Propriedades de estilo dos elementos.

Elementos de nível superior

O elemento do contêiner mais externo do Documentos Google é um documento. Essa é a unidade que pode ser salva no Google Drive, compartilhada com outros usuários e atualizada com texto e imagens.

Os elementos de nível superior de um recurso documents incluem Body, Header, Footer e vários outros atributos:

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

Neste guia, o Google apresenta uma visualização minimalista dos elementos estruturais do documento. Isso é uma questão de simplicidade e clareza. Para uma representação completa da estrutura do documento, use o utilitário descrito em Enviar conteúdo do documento como JSON.

Para manipular recursos globais de documentos fora do conteúdo de Body, é quase sempre melhor usar um ou mais modelos de documento, que podem ser usados como base para gerar novos documentos de forma programática. Para mais informações, consulte Mesclar texto em um documento.

Conteúdo do corpo

O Body normalmente tem todo o conteúdo do documento. A maioria dos itens que você pode, ou provavelmente quer usar, programaticamente são elementos do conteúdo de Body:

Figura 1. Estrutura do conteúdo do corpo.

Elemento estrutural

Um StructuralElement descreve o conteúdo que fornece estrutura ao documento. O conteúdo Body é uma sequência de objetos StructuralElement. Um elemento de conteúdo personaliza cada objeto StructuralElement, conforme mostrado no diagrama abaixo:

Figura 2. Elementos estruturais.

Os elementos estruturais e os objetos de conteúdo deles contêm todos os componentes visuais do documento. Isso inclui o texto, as imagens inline e a formatação.

Os tipos Header, Footer e Footnote têm elementos de conteúdo que também contêm uma sequência de elementos estruturais.

Estrutura do parágrafo

Um Paragraph é um StructuralElement que representa um parágrafo. tem um intervalo de conteúdo que termina com um caractere de nova linha; Ele é composto pelos seguintes objetos:

• ParagraphElement: descreve o conteúdo em um parágrafo.
• ParagraphStyle: um elemento opcional que define explicitamente as propriedades de estilo do parágrafo.
• Bullet: se o parágrafo fizer parte de uma lista, é um elemento opcional que fornece a especificação do marcador.

O ParagraphElement funciona de maneira semelhante a uma StructuralElement. Um conjunto de tipos de elementos de conteúdo (como ColumnBreak e Equation) personaliza o próprio ParagraphElement, conforme mostrado no diagrama abaixo:

Figura 3. Estrutura dos elementos do parágrafo.

Para conferir um exemplo de uma estrutura de documento completa, consulte o exemplo de documento no formato JSON. Na saída, você pode ver muitos dos principais elementos estruturais e de conteúdo, bem como o uso de índices de início e fim, conforme descrito em uma seção a seguir.

Corridas de texto

Um TextRun é um ParagraphElement que 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 nunca ultrapassam os limites de parágrafo. O conteúdo é dividido após um caractere de nova linha para formar execuções de texto separadas. Por exemplo, considere um documento pequeno como o seguinte:

Figura 4. Um documento pequeno.

O diagrama a seguir mostra como visualizar a sequência de parágrafos no documento anterior, cada um com o próprio TextRun e configurações Bullet opcionais.

Figura 5. Estrutura de uma execução de texto.

AutoText

AutoText é uma ParagraphElement que representa um espaço no texto que é substituído dinamicamente por conteúdo que pode mudar com o tempo. No app Documentos, isso é usado para números de página.

Índices inicial e final

Quando você atualiza o conteúdo de um documento, cada atualização ocorre em um local ou em um intervalo do documento. Esses locais e intervalos são especificados usando índices, que representam um deslocamento em um segmento de documento. Um segmento é o corpo, cabeçalho, rodapé ou nota de rodapé que contém elementos estruturais ou de conteúdo. Os índices dos elementos dentro de um segmento são relativos ao início desse segmento.

A maioria dos elementos no conteúdo do corpo tem as propriedades startIndex e endIndex baseadas em zero. Eles indicam o deslocamento do início e do fim de um elemento em relação ao início do segmento que o abrange. Para mais informações sobre como ordenar suas chamadas em lote da API Docs, consulte Atualizações em lote.

Os índices são medidos em unidades de código UTF-16. Ou seja, pares alternativos consomem dois índices. Por exemplo, o emoji "GRINNING FACE", GH, é representado como \uD83D\uDE00 e consome 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 elementos não incluídos no conteúdo não têm essas propriedades de índice. Eles têm escopo global e não têm o conceito de posição.

Os tipos de "personalização" para elementos estruturais (SectionBreak, TableOfContents, Table e Paragraph) não têm esses índices porque StructuralElement envolvem esses campos. Isso também se aplica aos tipos de personalização contidos em um ParagraphElement, como TextRun, AutoText e PageBreak.

Acessar elementos

Muitos elementos podem ser modificados com o método documents.batchUpdate. Por exemplo, usando InsertTextRequest, é possível mudar o conteúdo de qualquer elemento com texto. Da mesma forma, você pode 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 documents.get para fazer um despejo JSON do documento completo. Depois, você pode analisar o JSON resultante para encontrar os valores de elementos individuais. Para mais informações, consulte Conteúdo do documento de saída como JSON.

Analisar o conteúdo pode ser benéfico para vários casos de uso. Pense, por exemplo, em um aplicativo de catalogação de documentos que lista os documentos encontrados. 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:

Figura 6. Estrutura de um catálogo de documentos.

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

Herança da propriedade

Um StructuralElement pode herdar propriedades de seus objetos pai. As propriedades de um objeto, incluindo as que ele define e as herdadas, determinam a aparência final dele.

A formatação de caracteres de texto determina como o texto é renderizado em um documento, como negrito, itálico e sublinhado. A formatação aplicada modifica a formatação padrão herdada do TextStyle do parágrafo subjacente. Por outro lado, todos os caracteres com uma formatação que você não definir continuarão a herdar dos estilos do parágrafo.

A formatação de parágrafo determina como os blocos de texto são renderizados em um documento, como alinhamento, bordas e recuo. A formatação aplicada modifica a formatação padrão herdada do ParagraphStyle. Por outro lado, todos os recursos de formatação que você não definir continuarão a herdar do estilo de parágrafo.

Temas relacionados

• Solicitações e respostas
• Regras e comportamento de edição estrutural