Estrutura de um arquivo do Documentos Google

Para usar a API Google Docs de maneira eficaz, você deve entender as arquitetura de um documento do Google Docs e os elementos que compõem um do documento, bem como a relação entre eles. Nesta página, você encontra visão geral detalhada destes 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. Esta é a que pode ser salvo no Google Drive, compartilhado com outros usuários e atualizado com texto e imagens.

Os elementos de nível superior de uma documents. recurso incluem os Tabs dele, SuggestionsViewMode, e outros atributos:

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

Guias

Um único documento pode conter várias guias, que têm conteúdos de texto diferentes. A propriedade tabs do documento é uma 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, que são aninhadas diretamente. abaixo dele).
  • DocumentTab: Representa o conteúdo de texto de uma guia.
.
Estrutura das guias de um documento.
Figura 1. Estrutura das guias de um documento.

As próximas seções oferecem uma breve visão geral da hierarquia das guias do documento. as Representação JSON da guia também fornece informações mais detalhadas. Consulte Trabalhar com guias para mais informações sobre o recurso de guias.

Para manipular recursos globais da guia de documentos fora do conteúdo do Body, é é quase sempre melhor usar um ou mais modelos de documento, que você pode usar como uma 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 da guia de um documento. A maioria itens que você pode ou provavelmente gostaria de usar de forma programática são elementos dentro o conteúdo Body:

Estrutura do conteúdo do corpo.
Figura 2. Estrutura do conteúdo do corpo.

Elemento estrutural

Uma StructuralElement descreve o conteúdo que estrutura o documento. O conteúdo de Body é uma sequência de objetos StructuralElement. Um elemento de conteúdo personaliza cada um StructuralElement, conforme mostrado no diagrama a seguir:

Elementos estruturais.
Figura 3. Elementos estruturais.

Os elementos estruturais e os objetos de conteúdo deles 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 representando um parágrafo. Ele tem uma variedade de conteúdo e termina com um caractere de nova linha. Ele é composto pelos seguintes objetos:

  • ParagraphElement: Descreve o conteúdo em um parágrafo.
  • ParagraphStyle: um O 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 o marcador especificação.

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

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

Para obter um exemplo de uma estrutura completa de documento, consulte o documento exemplo no formato JSON. Na saída, é possível ver muitos dos principais elementos estruturais e de conteúdo, bem como o uso de e índices finais, conforme descrito na 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 o parágrafo pode conter várias sequências de texto, mas o texto corre nunca entre parágrafos limites. O conteúdo é dividido após um caractere de nova linha para formar um texto separado é executado. Por exemplo, considere um documento pequeno como o seguinte:

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 o próprio TextRun e Bullet opcionais configurações.

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

AutoText

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

Índices inicial e final

Quando você atualiza o conteúdo da guia de um documento, cada atualização leva lugar em um local ou em um intervalo dentro do documento. Esses locais e intervalos são especificados usando índices, que representam um deslocamento dentro de um que contém o segmento do documento. Um segmento é o corpo, cabeçalho, rodapé ou nota de rodapé com 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 o startIndex baseado em zero e endIndex propriedades. Eles indicam o deslocamento do início e do início de um elemento final, 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 Batch atualizações.

Os índices são medidos em unidades de código UTF-16. Ou seja, pares alternativos consomem dois índices. Por exemplo, "ROXIDO" emoji, , é representado como \uD83D\uDE00 e consumirá dois índices.

Para elementos no corpo de um documento, os índices representam deslocamentos do começo do conteúdo do corpo, que é a "raiz", .

A parte de "personalização" tipos para estruturas elementos: SectionBreak, TableOfContents, Table e Paragraph—não têm esses índices porque os respectivos StructuralElement tem estes campos. Isso também se aplica à personalização tipos contidos em um ParagraphElement, como TextRun, AutoText e PageBreak

Acessar elementos

Muitos elementos podem ser modificados com o documents.batchUpdate . Por exemplo, usar InsertTextRequest, é possível alterar o conteúdo de qualquer elemento que contenha texto. Da mesma forma, é possível usam 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 método documents.get para receber uma Despejo JSON do documento completo. É possível analisar o JSON resultante para encontrar os valores de elementos individuais. Para mais informações, consulte a seção Saída do documento em formato JSON.

Analisar o conteúdo pode ser benéfico para vários casos de uso. Considere, por um aplicativo de catalogação de documentos que lista os documentos encontrados. Este app pode extrair o título, ID da revisão e número da página inicial do URL de um documento conforme mostrado no diagrama a seguir:

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

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

Herança da propriedade

Um StructuralElement pode herdar propriedades de seus objetos pai. Um propriedades do objeto, incluindo as que ele define e as herdadas, determinar sua aparência visual 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 o padrão a formatação herdada do argumento TextStyle Da mesma forma, qualquer caracteres cuja formatação você não definir continuem a herdar do de 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 que você aplica substitui a formatação padrão herdada do ParagraphStyle. Por outro lado, todos os recursos de formatação não configurados continuarão a herdar o estilo de parágrafo.