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 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 os Tab
s,
SuggestionsViewMode
e outros atributos:
document: { title: ... , revisionId: ... , documentId: ... , suggestionsViewMode: ... , tabs: ... }
Guias
Um único documento pode conter várias guias, com diferentes conteúdos em nível de 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.
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 fizer parte de uma lista, é um elemento opcional que fornece a especificação do marcador.
O ParagraphElement
funciona de forma semelhante a um StructuralElement
. Um conjunto de
tipos de elementos de conteúdo (como
ColumnBreak
e
Equation
) personaliza o
próprio ParagraphElement
, conforme mostrado no diagrama abaixo:
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 fim, 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:
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.
AutoText
AutoText
é um
ParagraphElement
que representa um ponto 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 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 dentro de um segmento de documento que o 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 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", KB, é 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 com 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:
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 modifica a formatação
padrão herdada do TextStyle
do parágrafo
subjacente. Por outro lado, todos
os caracteres que não tiverem uma formatação definida vão 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.