Per utilizzare l'API Google Docs in modo efficace, è necessario comprendere l'architettura di un documento di Documenti Google e gli elementi che lo costituiscono, nonché la relazione tra loro. Questa pagina fornisce 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. 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 Body, Header, Footer e diversi altri attributi:
document: {
body: ... ,
documentStyle: ... ,
lists: ... ,
documentId: ... ,
namedStyles: ... ,
revisionId: ... ,
title: ...
}
Per gestire le funzionalità globali dei documenti al di fuori dei contenuti 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, consulta
Unire testo in un documento.
Corpo del testo
L'oggetto Body in genere include l'intero contenuto del documento. La maggior parte degli elementi che puoi, o che probabilmente vorrai utilizzare in modo programmatico, sono elementi all'interno dei contenuti di Body:
Elemento strutturale
Un elemento StructuralElement
descrive i contenuti che strutturano il documento. I contenuti Body sono
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. Ciò include testo, immagini in linea e formattazione.
Struttura del paragrafo
Una Paragraph è una StructuralElement che rappresenta un paragrafo. Presenta una serie di contenuti
terminata con un carattere di nuova riga. È composto dai seguenti oggetti:
ParagraphElement: descrive i contenuti di un paragrafo.ParagraphStyle: un elemento facoltativo che imposta in modo esplicito 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 un StructuralElement. Un insieme di tipi di elementi di contenuti (come ColumnBreak e Equation) personalizza il proprio ParagraphElement, come mostrato nel seguente diagramma:
Per un esempio di struttura completa di un documento, vedi 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 fine, come descritto in una sezione che segue.
Esecuzioni testo
Un elemento TextRun è un ParagraphElement che rappresenta una stringa di testo contigua con lo stesso stile di testo. Un paragrafo può contenere più esecuzioni di testo, che però non superano mai i confini dei paragrafi. 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 visualizzare la sequenza di paragrafi nel documento precedente, ciascuno con le proprie impostazioni TextRun e Bullet facoltative.
AutoText
AutoText è una ParagraphElement che rappresenta uno spazio nel testo che viene sostituito dinamicamente con contenuti che possono cambiare nel tempo. In Documenti, è usata per
i numeri di pagina.
Indici di inizio e fine
Quando aggiorni i contenuti di un documento, ogni aggiornamento avviene in una posizione o in un intervallo all'interno del documento. Le località e gli intervalli vengono specificati utilizzando gli indici, che rappresentano un offset all'interno di un segmento di documenti contenitore. 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 del segmento.
La maggior parte degli elementi all'interno dei contenuti del corpo ha le proprietà startIndex e endIndex in base zero. Indica 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 API Documenti batch, consulta Aggiornamenti batch.
Gli indici sono misurati in unità di codice UTF-16. Ciò significa che le coppie di surrogati
consumano due indici. Ad esempio, l'emoji "FASCIA CON RINGRAZIAMENTO", tan, è 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" degli elementi strutturali,
SectionBreak,
TableOfContents,
Table e
Paragraph, non hanno questi indici perché il loro Contenuto
StructuralElement include 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, con InsertTextRequest puoi modificare i contenuti 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 codice JSON risultante
per trovare i valori dei singoli elementi. Per ulteriori informazioni, consulta Generare i contenuti del documento come JSON.
L'analisi dei contenuti può essere utile per vari casi d'uso. Prendi ad esempio un documento che cataloga i documenti di un'applicazione che trova. Questa app può estrarre il titolo, l'ID revisione e il numero di pagina iniziale di un documento, come mostrato nel seguente diagramma:
Poiché non esistono metodi per leggere esplicitamente queste impostazioni, l'app deve ottenere l'intero documento e quindi analizzare il codice JSON per estrarre questi valori.
Eredità della proprietà
Un elemento StructuralElement può ereditare le proprietà dagli oggetti padre. Le proprietà di un oggetto, comprese quelle che definisce e quelle che eredita, determinano il suo aspetto visivo finale.
La formattazione dei caratteri del testo determina come il testo viene visualizzato in un documento, ad esempio grassetto, corsivo e sottolineato. La formattazione che applichi sostituisce la formattazione predefinita ereditata dal parametro TextStyle del paragrafo sottostante. Al contrario, i caratteri la cui formattazione non imposti continuano a essere ereditati dagli stili del paragrafo.
La formattazione del paragrafo determina il modo in cui vengono visualizzati blocchi di testo in un documento, ad esempio allineamento, bordi e rientro. La formattazione applicata sostituisce la formattazione predefinita ereditata dall'elemento ParagraphStyle sottostante.
Al contrario, le caratteristiche di formattazione che non imposti continuano a ereditare dallo
stile di paragrafo.