Per utilizzare l'API Google Docs in modo efficace, devi comprendere l'architettura di un documento Google Docs e gli elementi che lo compongono, nonché la relazione tra questi elementi. Questa pagina fornisce una panoramica dettagliata di questi argomenti:
- Un modello concettuale degli elementi del documento
- Come l'API Docs rappresenta questi elementi
- Le proprietà di stile degli elementi
Elementi di primo livello
L'elemento contenitore più esterno in Documenti Google è un documento. Questa è l'unità che può essere salvata su Google Drive, condivisa con altri utenti e aggiornata con testo e immagini.
Gli elementi di primo livello di una risorsa
documents includono
i relativi Tab,
SuggestionsViewMode
e altri attributi:
document: {
title: ... ,
revisionId: ... ,
documentId: ... ,
suggestionsViewMode: ... ,
tabs: ...
}
Schede
Un singolo documento può contenere più schede,
che hanno contenuti a livello di testo diversi. La proprietà tabs del documento è una
sequenza di oggetti Tab. Un Tab è composto dai seguenti campi:
TabProperties: contiene gli attributi di una scheda, ad esempio ID, titolo e indice.childTabs: mostra le schede secondarie di una scheda (le schede nidificate direttamente sotto di essa).DocumentTab: Rappresenta il contenuto di testo di una scheda.
Le sezioni successive forniscono una breve panoramica della gerarchia delle schede del documento; la rappresentazione JSON delle schede fornisce anche informazioni più dettagliate. Per ulteriori informazioni sulla funzionalità delle schede, consulta la sezione Utilizzare le schede.
Per manipolare le funzionalità delle schede dei documenti globali al di fuori dei contenuti Body, è
quasi sempre meglio utilizzare uno o più modelli di documenti, che puoi utilizzare come
base per generare nuovi documenti in modo programmatico. Per saperne di più, vedi
Unire il testo in un documento.
Contenuto del corpo
Il Body in genere contiene tutti i contenuti di una scheda del documento. La maggior parte degli elementi che puoi o vorresti utilizzare a livello di programmazione si trova all'interno dei contenuti Body:
Elemento strutturale
Un StructuralElement
descrive i contenuti che forniscono struttura al documento. I contenuti Body sono
una sequenza di oggetti StructuralElement. Un elemento di contenuti personalizza ogni oggetto StructuralElement, come mostrato nel seguente diagramma:
Gli elementi strutturali e i relativi oggetti di contenuti contengono tutti i componenti visivi all'interno del documento. Sono inclusi testo, immagini incorporate e formattazione.
Struttura del paragrafo
Paragraph è un
StructuralElement che rappresenta un paragrafo. Contiene una serie di contenuti
terminati con un carattere di nuova riga. È composto dai seguenti oggetti:
ParagraphElement: Descrive i contenuti all'interno di un paragrafo.ParagraphStyle: Un elemento facoltativo che imposta esplicitamente le proprietà di stile per il paragrafo.Bullet: se il paragrafo fa parte di un elenco, un elemento facoltativo che fornisce la specifica del punto elenco.
Il ParagraphElement funziona un po' come un StructuralElement. Un insieme di tipi di elementi dei contenuti (ad esempio ColumnBreak e Equation) personalizza il proprio ParagraphElement, come mostrato nel seguente diagramma:
Per un esempio di struttura completa del documento, consulta l'esempio di documento in formato JSON. Nell'output puoi vedere molti degli elementi strutturali e di contenuti chiave, nonché l'utilizzo degli indici di inizio e fine, come descritto in una sezione successiva.
Esecuzioni di testo
Un TextRun è un
ParagraphElement
che rappresenta una stringa di testo contigua con lo stesso stile di testo. Un
paragrafo può contenere più sequenze di testo, ma queste non superano mai i limiti
del paragrafo. I contenuti vengono suddivisi dopo un carattere di nuova riga per formare esecuzioni di testo separate. Ad esempio, considera un documento molto piccolo come il seguente:
Il seguente diagramma mostra come visualizzare la sequenza di paragrafi
nel documento precedente, ognuno con le proprie impostazioni TextRun e Bullet
facoltative.
AutoText
AutoText è un
ParagraphElement che rappresenta un punto nel testo che viene sostituito dinamicamente
con contenuti che possono cambiare nel tempo. In Documenti, questo viene utilizzato per
i numeri di pagina.
Indici iniziale e finale
Quando apporti aggiornamenti ai contenuti di una scheda di un documento, ogni aggiornamento viene eseguito in una posizione o in un intervallo all'interno del documento. Queste posizioni e intervalli vengono specificati utilizzando indici, che rappresentano un offset all'interno di un segmento del documento contenitore. Un segmento è il corpo, l'intestazione, il piè di pagina o la nota a piè di pagina contenente elementi strutturali o di contenuti. Gli indici degli elementi all'interno di un segmento sono relativi all'inizio del segmento.
La maggior parte degli elementi all'interno del corpo del contenuto ha le proprietà startIndex e
endIndex basate su zero. Indicano l'offset dell'inizio e della fine di un elemento rispetto all'inizio del segmento contenitore. Per saperne di più su come ordinare le chiamate API batch di Documenti, consulta Aggiornamenti
batch.
Gli indici vengono misurati in unità di codice UTF-16. Ciò significa che le coppie di surrogati consumano
due indici. Ad esempio, l'emoji "FACCIA SORRIDENTE", 😄, è rappresentata come
\uD83D\uDE00 e consuma due indici.
Per gli elementi all'interno del corpo di un documento, gli indici rappresentano gli offset dall'inizio dei contenuti del corpo, che è l'elemento "radice".
I tipi "personalizzazione" per gli elementi strutturali SectionBreak, TableOfContents, Table e Paragraph non hanno questi indici perché il relativo StructuralElement contiene questi campi. Ciò vale anche per i tipi di personalizzazione contenuti in un ParagraphElement, ad esempio TextRun, AutoText e PageBreak.
Elementi di accesso
Molti elementi sono modificabili con il metodo
documents.batchUpdate. Ad esempio, utilizzando
InsertTextRequest,
puoi modificare il contenuto di qualsiasi elemento contenente testo. Allo stesso modo, puoi
utilizzare
UpdateTextStyleRequest
per applicare la formattazione a un intervallo di testo contenuto in uno o più elementi.
Per leggere gli elementi del documento, utilizza il metodo
documents.get per
ottenere un dump JSON del documento completo. Puoi quindi analizzare il JSON risultante
per trovare i valori dei singoli elementi. Per ulteriori informazioni, consulta la sezione
Output document contents as JSON.
L'analisi del contenuto può essere utile per vari casi d'uso. Prendi in considerazione, ad esempio, un'applicazione di catalogazione dei documenti che elenca i documenti che trova. Questa app può estrarre il titolo, l'ID revisione e il numero di pagina iniziale delle schede di un documento, come mostrato nel seguente diagramma:
Poiché non esistono metodi per leggere esplicitamente queste impostazioni, la tua app deve recuperare l'intero documento e poi analizzare il JSON per estrarre questi valori.
Eredità della proprietà
Un StructuralElement può ereditare le proprietà dai relativi oggetti principali. Le proprietà di un oggetto, incluse quelle che definisce e quelle che eredita, determinano il suo aspetto visivo finale.
La formattazione dei caratteri di testo determina la modalità di rendering del testo in un documento, ad esempio
grassetto, corsivo e sottolineatura. La formattazione che applichi sostituisce quella predefinita
ereditata dal TextStyle del paragrafo sottostante.
Al contrario, tutti i caratteri la cui formattazione non viene impostata continuano a ereditare
gli stili del paragrafo.
La formattazione dei paragrafi determina il modo in cui i blocchi di testo vengono visualizzati in un documento,
ad esempio allineamento, bordi e rientro. La formattazione che applichi
override della formattazione predefinita ereditata dal ParagraphStyle sottostante.
Al contrario, tutte le funzionalità di formattazione che non imposti continuano a essere ereditate dallo stile del paragrafo.