Struttura di un documento di Documenti Google

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:

Struttura dei contenuti del corpo.
Figura 1. Struttura dei contenuti del corpo.

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:

Elementi strutturali.
Figura 2. Elementi strutturali.

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:

Struttura degli elementi paragrafo.
Figura 3. Struttura degli elementi paragrafo.

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:

Documento di piccole dimensioni con paragrafi ed elenchi puntati.
Figura 4. Un documento di piccole dimensioni.

Il seguente diagramma mostra come potresti visualizzare la sequenza di paragrafi nel documento precedente, ciascuno con le proprie impostazioni TextRun e Bullet facoltative.

Struttura di un'esecuzione di testo.
Figura 5. Struttura di un'esecuzione di testo.

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:

Struttura di un catalogo di documenti.
Figura 6. Struttura di un catalogo di documenti.

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.