Per utilizzare l'API Documenti Google in modo efficace, devi comprendere l'architettura di un documento di Documenti Google 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 Documenti 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 in Google Drive, condivisa con altri utenti e aggiornata con testo e immagini.
Gli elementi di primo livello di una
documents risorsa includono
i relativi Tabs,
SuggestionsViewMode,
e altri attributi:
document: {
title: ... ,
revisionId: ... ,
documentId: ... ,
suggestionsViewMode: ... ,
tabs: ...
}
Schede
Un singolo documento può contenere più schede,
con 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, come ID, titolo e indice.childTabs: espone le schede secondarie di una scheda (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 dei documenti; la Tab rappresentazione JSON fornisce anche informazioni più dettagliate. Per ulteriori informazioni sulla funzionalità delle schede, consulta Utilizzare le schede.
Per manipolare le funzionalità delle schede dei documenti globali al di fuori del contenuto Body, è quasi sempre meglio utilizzare uno o più modelli di documenti, che puoi utilizzare come base per generare nuovi documenti a livello di programmazione. Per ulteriori informazioni, consulta
Unire testo in un documento.
Contenuto del corpo
Il Body in genere contiene tutti i contenuti della scheda di un documento. La maggior parte degli elementi che puoi o vorresti utilizzare a livello di programmazione sono elementi all'interno del contenuto Body:
Elemento strutturale
Un StructuralElement
descrive i contenuti che forniscono la struttura al documento. Il contenuto Body è una sequenza di oggetti StructuralElement. Un elemento di contenuto 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. Sono inclusi il testo, le immagini in linea e la formattazione.
Struttura del paragrafo
Un Paragraph è un
StructuralElement che rappresenta un paragrafo. Ha un intervallo di contenuti terminato 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.
ParagraphElement funziona in modo simile a StructuralElement. Un insieme di
tipi di elementi di contenuto (come
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 contenuto chiave, nonché l'utilizzo degli indici di inizio e fine come descritto in una sezione successiva.
Sequenze 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 le sequenze di testo non superano mai i limiti del paragrafo. I contenuti vengono suddivisi dopo un carattere di nuova riga per formare sequenze di testo separate. Ad esempio, considera un piccolo documento come il seguente:
Il seguente diagramma mostra come potresti 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, viene utilizzato per i numeri di pagina.
Indici di inizio e fine
Quando apporti aggiornamenti ai contenuti della scheda di un documento, ogni aggiornamento viene eseguito in una posizione o in un intervallo all'interno del documento. Queste posizioni e questi intervalli vengono specificati utilizzando indici, che rappresentano un offset all'interno di un segmento di documento contenitore . Un segmento è il corpo, l'intestazione, il piè di pagina o la nota a piè di pagina contenente elementi strutturali o di contenuto. Gli indici degli elementi all'interno di un segmento sono relativi all'inizio di quel segmento.
La maggior parte degli elementi all'interno del contenuto del corpo ha le proprietà startIndex e endIndex basate su zero. Questi indicano l'offset dell'inizio e della fine di un elemento, rispetto all'inizio del segmento di inclusione. Per ulteriori informazioni
su come ordinare le chiamate API Documenti in batch, consulta Aggiornamenti
in batch.
Gli indici vengono misurati in unità di codice UTF-16. Ciò significa che le coppie surrogate consumano due indici. Ad esempio, l'emoji "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 del contenuto del corpo, che è l'elemento "root".
I tipi di "personalizzazione" per gli elementi strutturali
—SectionBreak,
TableOfContents,
Table e
Paragraph—non hanno questi indici perché il relativo
StructuralElement ha questi campi. Questo vale anche per i tipi di personalizzazione
contenuti in un ParagraphElement, come TextRun, AutoText, e
PageBreak.
Accedere agli elementi
Molti elementi sono modificabili con il
documents.batchUpdate
metodo. 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
documents.get metodo 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
Output document contents as JSON.
L'analisi dei contenuti può essere utile per vari casi d'uso. Considera, 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 l'aspetto visivo finale.
La formattazione dei caratteri di testo determina la modalità di rendering del testo in un documento, ad esempio grassetto, corsivo e sottolineato. La formattazione che applichi sostituisce la formattazione predefinita
ereditata da
TextStyle del paragrafo sottostante.
Al contrario, tutti i caratteri la cui formattazione non è impostata continuano a ereditare gli stili del paragrafo.
La formattazione dei paragrafi determina la modalità di rendering dei blocchi di testo in un documento, ad esempio allineamento, bordi e rientro. La formattazione che applichi sostituisce la formattazione predefinita ereditata da ParagraphStyle sottostante.
Al contrario, tutte le funzionalità di formattazione che non imposti continuano a ereditare lo stile del paragrafo.