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 oggetti Tab. Un Tab è costituito 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 della scheda fornisce 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 dei contenuti Body, è quasi sempre meglio utilizzare uno o più modelli di documenti, che puoi utilizzare come base per generare nuovi documenti tramite programmazione. 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 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 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 un 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.
Inserimenti di testo
Un TextRun è un
ParagraphElement
che rappresenta una stringa di testo contigua con lo stesso stile di testo. Un paragrafo può contenere più righe di testo, ma queste non possono mai superare i confini del paragrafo. I contenuti vengono suddivisi dopo un carattere di nuova riga per formare flussi di testo distinti. Ad esempio, prendi in considerazione un documento molto piccolo come il seguente:
Il seguente diagramma mostra come 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 di 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 del contenuto del corpo 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 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 e Paragraph) non hanno questi indici perché il StructuralElement che li racchiude li ha. Lo stesso vale 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 i contenuti di qualsiasi elemento contenente testo. Analogamente, 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 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 analizzare il 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 la cui formattazione non è 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 l'allineamento, i bordi e il 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 lo stile di paragrafo.