Para usar a API Google Docs de forma eficaz, você precisa entender a arquitetura de um arquivo do Documentos Google e os elementos que o compõem, além da relação entre eles. Nesta página, você encontra uma visão geral detalhada destes tópicos:
- 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 no Documentos Google é um documento. Essa unidade 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: ... }
Para manipular recursos globais de documentos fora do conteúdo Body
, é
quase sempre melhor usar um ou mais modelos de documento, que podem ser usados como
base para gerar novos documentos de maneira programática. Para saber mais, consulte
Mesclar texto em um documento.
Conteúdo do corpo
O Body
normalmente contém o conteúdo completo do documento. A maioria dos itens que você
pode ou quer usar programaticamente são elementos do
conteúdo de Body
:
Elemento estrutural
Um StructuralElement
descreve o conteúdo que fornece estrutura para 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 respectivos objetos de conteúdo contêm todos os componentes visuais dentro do documento. Isso inclui o texto, as imagens inline e a formatação.
Estrutura do parágrafo
Uma Paragraph
é uma
StructuralElement
que representa um parágrafo. Inclui uma variedade de conteúdos
terminados 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 do marcador.
O ParagraphElement
funciona como uma 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:
Para um exemplo de estrutura completa de documento, consulte o exemplo de 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 em uma seção a seguir.
Execuções de texto
Uma TextRun
é uma
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 cruzam 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:
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 espaço no texto que é substituído dinamicamente
por conteúdo que pode mudar ao longo do tempo. No Documentos, isso é usado
para números de página.
Índices iniciais e finais
Quando você atualiza o conteúdo de um documento, cada atualização ocorre 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 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 dele.
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 incluído. Para saber mais sobre como ordenar chamadas da API Docs em lote, consulte Atualizações em lote.
Os índices são medidos em unidades de código UTF-16. Isso significa que pares substitutos consomem
dois índices. Por exemplo, o emoji "GRINNING FACE" demais é 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 tipos de "personalização" para elementos
estruturais (SectionBreak
,
TableOfContents
,
Table
e
Paragraph
) não têm esses índices porque StructuralElement
ao redor têm 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 que contenha 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 receber um
arquivo JSON do documento completo. Você pode analisar o JSON resultante para
encontrar os valores de elementos individuais. Para mais informações, consulte o Conteúdo
do documento de saída como JSON.
Analisar o conteúdo pode ser benéfico para vários casos de uso. Considere, por exemplo, um documento de catalogação que lista os documentos que 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 acessar o documento inteiro e analisar o JSON para extrair esses valores.
Herança da propriedade
Uma StructuralElement
pode herdar propriedades dos objetos pais. As
propriedades de um objeto, incluindo aquelas que ele define e as herdadas,
determinam a 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 a formatação
padrão herdada do TextStyle
do parágrafo subjacente. Por outro lado, todos
os caracteres com formatação não definida continuam 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
modifica a formatação padrão herdada do ParagraphStyle
.
Por outro lado, todos os recursos de formatação não definidos continuam a herdar do
estilo de parágrafo.