Esta página foi traduzida pela API Cloud Translation.

Estrutura de um arquivo do Documentos Google

Para usar a API Google Docs de maneira eficaz, é necessário entender a arquitetura de um documento do Google Docs e os elementos que o compõem, além da relação entre eles. Esta página oferece uma visão geral detalhada destes tópicos:

Um modelo conceitual dos elementos do documento
Como a API Docs representa esses elementos
As propriedades de estilo dos elementos

Elementos de nível superior

O elemento do contêiner mais externo nos 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 os Tabs, SuggestionsViewMode e outros atributos:

document: {
    title: ... ,
    revisionId: ... ,
    documentId: ... ,
    suggestionsViewMode: ... ,
    tabs: ...
}

Guias

Um único documento pode conter várias guias, que têm conteúdos diferentes no nível do texto. A propriedade tabs do documento é uma sequência de objetos Tab. Um Tab é composto pelos seguintes campos:

TabProperties: contém os atributos de uma guia, como ID, título e índice.
childTabs: expõe as guias filhas de uma guia (guias aninhadas diretamente abaixo dela).
DocumentTab: representa o conteúdo de texto de uma guia.

**Figura 1.** Estrutura das guias de um documento.

As seções a seguir fornecem uma breve visão geral da hierarquia de guias do documento. A representação JSON das guias também oferece informações mais detalhadas. Consulte Trabalhar com guias para mais informações sobre o recurso de guias.

Para manipular os recursos da guia de documentos globais fora do conteúdo Body, é quase sempre melhor usar um ou mais modelos de documentos, que podem ser usados como base para gerar novos documentos por programação. Para mais informações, consulte Mesclar texto em um documento.

Conteúdo do corpo

O Body geralmente contém o conteúdo completo da guia de um documento. A maioria dos itens que você pode ou gostaria de usar programaticamente são elementos dentro do conteúdo Body:

Elemento estrutural

Um StructuralElement descreve o conteúdo que estrutura o documento. O conteúdo Body é 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 contêm todos os componentes visuais no documento. Isso inclui o texto, as imagens inline e a formatação.

Estrutura do parágrafo

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

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

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

**Figura 4**. Estrutura dos elementos do parágrafo.

Para conferir um exemplo de 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 final, conforme descrito na próxima seção.

Execuções de texto

Um TextRun é um ParagraphElement que representa uma string de texto contígua com o mesmo estilo de texto. Um parágrafo pode conter várias execuções de texto, mas elas nunca atravessam os limites do parágrafo. O conteúdo é dividido após um caractere de nova linha para formar corridas de texto separadas. Por exemplo, considere um documento pequeno como este:

Documento pequeno com parágrafos e lista com marcadores. — **Figura 5.** Um documento pequeno.

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

**Figura 6.** Estrutura de uma execução de texto.

AutoText

AutoText é um ParagraphElement que representa um ponto no texto que é substituído dinamicamente por conteúdo que pode mudar com o tempo. Nos Documentos, esse recurso é usado para números de página.

Índices inicial e final

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

A maioria dos elementos no conteúdo do corpo tem as propriedades startIndex e endIndex com base 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 envolve. Para mais informações sobre como ordenar as chamadas em lote da API Docs, consulte Atualizações em lote.

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 "RISO", 😄, é representado como \uD83D\uDE00 e consome dois índices.

Para elementos no corpo de um documento, os índices representam deslocamentos do 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 StructuralElement que os contém tem esses campos. Isso também se aplica aos tipos de personalização contidas 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 que contenha texto. Da mesma forma, é possível usar UpdateTextStyleRequest para aplicar a 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 extrair um despejo em JSON do documento completo. Em seguida, você pode analisar o JSON resultante para encontrar os valores de elementos individuais. Para mais informações, consulte a página Saída do conteúdo do documento como JSON.

Analisar o conteúdo pode ser benéfico para vários casos de uso. Considere, por exemplo, 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 das guias de um documento, conforme mostrado no diagrama abaixo:

**Figura 7**. Estrutura de um catálogo de documentos.

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

Herança da propriedade

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

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 substitui a formatação padrão herdada do TextStyle do parágrafo principal. Por outro lado, qualquer caractere que não tiver uma formatação definida continua a herdar os 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 substitui a formatação padrão herdada do ParagraphStyle. Por outro lado, os recursos de formatação que você não definir vão continuar sendo herdados do estilo de parágrafo.