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 di essi. Questa pagina fornisce una panoramica dettagliata dei seguenti 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. Si tratta dell'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 Tab,
SuggestionsViewMode e altri attributi:
document: {
title: ... ,
revisionId: ... ,
documentId: ... ,
suggestionsViewMode: ... ,
tabs: ...
}
Schede
Un singolo documento può contenere più schede, che hanno contenuti diversi a livello di testo. La proprietà tabs del documento è una
sequenza di Tab oggetti. 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 (schede nidificate direttamente al di sotto).DocumentTab: rappresenta il contenuto di testo di una scheda.
Le sezioni successive forniscono una breve panoramica della gerarchia delle schede del documento. Anche la rappresentazione JSON delle schede fornisce informazioni più dettagliate. Per ulteriori informazioni sulla funzionalità delle schede, consulta Utilizzare le schede.
Per manipolare le funzionalità globali delle schede 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 saperne di più, consulta
Unire il testo in un documento.
Contenuto del corpo
In genere, Body contiene i contenuti completi della scheda di un documento. La maggior parte degli elementi che puoi o probabilmente vorresti utilizzare in modo programmatico sono elementi all'interno dei contenuti Body:
Elemento strutturale
Un StructuralElement descrive i contenuti che forniscono struttura al documento. I contenuti di Body sono una sequenza di oggetti StructuralElement. Un elemento di contenuto personalizza ogni
StructuralElement oggetto, 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 incorporate e la formattazione.
Struttura del paragrafo
Un 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 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 in modo simile a un StructuralElement. Un insieme di tipi di elementi di contenuto (ad esempio ColumnBreak e Equation) personalizza il proprio ParagraphElement, come mostrato nel seguente diagramma:
Per un esempio di struttura di documento completa, consulta l'esempio di documento in formato JSON. Nell'output puoi vedere molti degli elementi strutturali e dei contenuti chiave, nonché l'utilizzo degli indici di inizio e di fine come descritto nella sezione successiva.
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, prendi in considerazione un documento molto piccolo 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 è un
ParagraphElement che rappresenta un punto del 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 avviene in una posizione o in un intervallo all'interno del documento. Queste posizioni e intervalli vengono specificati utilizzando gli indici, che rappresentano un offset all'interno di un segmento del documento contenente. 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 del 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 racchiude. Per ulteriori informazioni su come ordinare le chiamate batch dell'API Documenti, consulta Aggiornamenti in 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 utilizza due indici.
Per gli elementi all'interno del corpo di un documento, gli indici rappresentano gli offset dall'inizio dei contenuti del corpo, ovvero l'elemento "root".
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.
Elementi di accesso
Molti elementi sono modificabili con il metodo
documents.batchUpdate. Ad esempio, utilizzando
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 JSON del documento completo. Puoi quindi analizzare il JSON risultante per trovare i valori dei singoli elementi. Per ulteriori informazioni, consulta la sezione Eseguire l'output dei contenuti del documento come JSON.
L'analisi dei contenuti può essere utile per vari casi d'uso. Prendi ad esempio un'applicazione di catalogazione dei documenti che elenca i documenti trovati. 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 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, determinano la sua apparenza visiva finale.
La formattazione dei caratteri del testo determina la modalità di visualizzazione del testo in un documento, ad esempio in grassetto, corsivo e sottolineato. La formattazione applicata sostituisce la formattazione predefinita ereditata da 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 dal ParagraphStyle sottostante.
Al contrario, tutte le funzionalità di formattazione che non imposti continuano a ereditare
dallo stile paragrafo.