Per utilizzare l'API Google Documenti in modo efficace, devi conoscere l'architettura di un documento di Documenti Google e gli elementi che lo compongono, nonché la relazione tra questi. In questa pagina viene fornita una panoramica dettagliata di questi argomenti:
- Un modello concettuale degli elementi del documento
- In che modo 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. È 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 Body
, Header
Footer
e diversi altri attributi:
document: { body: ... , documentStyle: ... , lists: ... , documentId: ... , namedStyles: ... , revisionId: ... , title: ... }
Per manipolare le funzionalità globali dei documenti al di fuori dei contenuti di Body
, è quasi sempre meglio utilizzare uno o più modelli di documento, che puoi utilizzare come base per generare nuovi documenti in modo programmatico. Per maggiori informazioni, vedi Unire il testo in un documento.
Corpo del testo
In genere, Body
include i contenuti completi del documento. La maggior parte degli elementi che
puoi, o che probabilmente vorresti utilizzare, in modo programmatico sono elementi all'interno dei
contenuti Body
:
Elemento strutturale
Un elemento StructuralElement
descrive i contenuti che forniscono una struttura al documento. I contenuti Body
sono
una sequenza di oggetti StructuralElement
. Un elemento dei contenuti personalizza ogni
oggetto StructuralElement
, come mostrato nel seguente diagramma:
Gli elementi strutturali e i relativi oggetti di contenuto contengono tutti i componenti visivi all'interno del documento. Ciò include il testo, le immagini in linea e la formattazione.
Struttura del paragrafo
Un Paragraph
è un
StructuralElement
che rappresenta un paragrafo. Ha una serie di contenuti che termina
con un carattere di nuova riga. È costituita dai seguenti oggetti:
ParagraphElement
: descrive i contenuti di un paragrafo.ParagraphStyle
: un elemento facoltativo che imposta in modo esplicito le proprietà di stile del paragrafo.Bullet
: se il paragrafo fa parte di un elenco, un elemento facoltativo che fornisce la specifica del punto elenco.
Il ParagraphElement
funziona come un StructuralElement
. Un insieme di
tipi di elementi dei contenuti (come
ColumnBreak
e
Equation
) personalizza il proprio
ParagraphElement
, come mostrato nel seguente diagramma:
Per un esempio di struttura di documenti completa, vedi l'esempio di documento in formato JSON. Nell'output puoi vedere molti degli elementi chiave strutturali e dei contenuti, nonché l'utilizzo degli indici di inizio e fine, come descritto in una sezione di seguito.
Esecuzioni testo
Un TextRun
è un ParagraphElement
che rappresenta una stringa di testo contigua con lo stesso stile di testo. Un paragrafo può contenere più esecuzioni di testo, ma il testo non supera mai i confini del paragrafo. I contenuti vengono suddivisi dopo un carattere di nuova riga per formare esecuzioni di testo separate. Ad esempio, considera un documento di dimensioni ridotte come il seguente:
Il seguente diagramma mostra come potresti visualizzare la sequenza di paragrafi
nel documento precedente, ciascuno con le proprie impostazioni TextRun
e Bullet
facoltative.
AutoText
AutoText
è una 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 di inizio e di fine
Quando aggiorni i contenuti di un documento, ogni aggiornamento avviene in una posizione o in un intervallo all'interno del documento. Queste località e intervalli vengono specificati utilizzando indici, che rappresentano un offset all'interno di un segmento di documento contenente. Un segmento è il corpo, l'intestazione, il piè di pagina o la nota a piè di pagina che contiene elementi strutturali o di contenuti. Gli indici degli elementi all'interno di un segmento sono relativi all'inizio di tale segmento.
La maggior parte degli elementi all'interno dei contenuti del corpo ha le proprietà startIndex
e
endIndex
in base zero. Indicano l'offset dell'inizio e della fine di un elemento, rispetto all'inizio del segmento che lo contiene. Per ulteriori informazioni su come ordinare le chiamate batch all'API di Documenti, consulta Aggiornamenti batch.
Gli indici vengono misurati in unità di codice UTF-16. Ciò significa che le coppie di surrogati
utilizzano due indici. Ad esempio, l'emoji "GRINNING FACE" (GRINNING FACE", ); è 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 "principale".
I tipi di "personalizzazione" per gli elementi strutturali (SectionBreak
, TableOfContents
, Table
eParagraph
) non hanno questi indici perché StructuralElement
contiene questi campi. Questo vale anche per i tipi di personalizzazione contenuti in un ParagraphElement
, come TextRun
, AutoText
e PageBreak
.
Accedi agli elementi
Molti elementi sono modificabili con il metodo documents.batchUpdate
. Ad esempio, con InsertTextRequest
puoi modificare i contenuti di qualsiasi elemento contenente testo. Analogamente, puoi utilizzare l'icona 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 in formato JSON del documento completo. Puoi quindi analizzare il JSON risultante per
trovare i valori dei singoli elementi. Per maggiori informazioni, vedi Contenuti del documento di output come JSON.
L'analisi dei contenuti può essere utile in vari casi d'uso. Prendi ad esempio un'applicazione di catalogazione di documenti che elenca i documenti trovati. Questa app può estrarre il titolo, l'ID revisione e il numero della pagina iniziale di un documento, come mostrato nel seguente diagramma:
Poiché non esistono metodi per leggere queste impostazioni in modo esplicito, l'app deve recuperare l'intero documento e poi analizzare il codice JSON per estrarre questi valori.
Eredità della proprietà
Un StructuralElement
può ereditare proprietà dagli oggetti principali. Le proprietà di un oggetto, incluse quelle che definisce e quelle che eredita, ne determinano l'aspetto visivo finale.
La formattazione dei caratteri di testo determina come viene visualizzato il testo in un documento, ad esempio
grassetto, corsivo e sottolineatura. La formattazione applicata sostituisce la formattazione predefinita ereditata dall'elemento TextStyle
del paragrafo sottostante. Al contrario, tutti i caratteri di cui non hai impostato la formattazione continuano a ereditare dagli stili del paragrafo.
La formattazione del paragrafo determina il modo in cui vengono visualizzati i blocchi di testo in un documento, ad esempio allineamento, bordi e rientro. La formattazione applicata sostituisce la formattazione predefinita ereditata dalla sezione ParagraphStyle
sottostante.
Al contrario, tutte le funzionalità di formattazione che non imposti continuano a ereditare
dallo stile paragrafo.