Struttura di un documento di Documenti Google

Per utilizzare l'API di Documenti Google in modo efficace, devi conoscere le architettura di un documento di Documenti Google e gli elementi che compongono una documento di identità, 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
di Gemini Advanced.

Elementi di primo livello

L'elemento contenitore più esterno in Documenti Google è un documento. Questo è il 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 documents di una risorsa includono i relativi Tab, SuggestionsViewMode, e altri attributi:

document: {
    title: ... ,
    revisionId: ... ,
    documentId: ... ,
    suggestionsViewMode: ... ,
    tabs: ...
}

Schede

Un singolo documento può contenere più schede, che hanno contenuti a livello di testo diversi. La proprietà tabs del documento è una sequenza di Tab oggetti. Un Tab è composto dai seguenti campi:

  • TabProperties: Contiene gli attributi di una scheda, come ID, titolo e indice.
  • childTabs: mostra le schede secondarie di una scheda (schede nidificate direttamente sottostante).
  • DocumentTab: Rappresenta i contenuti testuali di una scheda.
di Gemini Advanced.
Struttura delle schede di un documento.
Figura 1. Struttura delle schede di un documento.

Le sezioni successive forniscono una breve panoramica della gerarchia delle schede del documento. il Rappresentazione JSON delle schede fornisce informazioni più dettagliate. Vedi Utilizzare le schede. per ulteriori informazioni sulla funzionalità delle schede.

Per manipolare le funzionalità globali delle schede dei documenti al di fuori dei contenuti di Body, è preferibile utilizzare uno o più modelli di documento, che possono essere per generare nuovi documenti in modo programmatico. Per ulteriori informazioni, vedi Unisci il testo in un documento.

Corpo del testo

Body in genere include tutti i contenuti della scheda di un documento. La maggior parte gli elementi che puoi, o che probabilmente vorresti utilizzare, in modo programmatico sono gli elementi i contenuti di Body:

Struttura dei contenuti del corpo.
. Figura 2. Struttura dei contenuti del corpo.

Elemento strutturale

Un StructuralElement descrive i contenuti che forniscono una struttura al documento. I contenuti di Body sono una sequenza di StructuralElement oggetti. Un elemento dei contenuti personalizza ogni StructuralElement, come mostrato nel seguente diagramma:

Elementi strutturali.
. Figura 3. 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. Presenta 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 il punto elenco e la specifica del prodotto.

Il ParagraphElement funziona come un StructuralElement. Un insieme di tipi di elementi dei contenuti (come ColumnBreak e Equation) personalizza la sua ParagraphElement, come illustrato nel seguente diagramma:

Struttura degli elementi paragrafo.
. Figura 4. Struttura degli elementi paragrafo.

Per un esempio di struttura completa di un documento, vedi il documento esempio in formato JSON. Nell'output puoi vedere molti degli elementi chiave strutturali e dei contenuti, oltre all'uso di parti come descritto in una sezione successiva.

Esecuzioni testo

Un TextRun è un ParagraphElement che rappresenta una stringa di testo contigua con lo stesso stile di testo. R un paragrafo può contenere più esecuzioni di testo, ma il testo non viene mai completato confini. I contenuti vengono suddivisi dopo un carattere di nuova riga per formare un testo separato viene eseguito. Ad esempio, considera un documento di dimensioni ridotte come il seguente:

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

Il seguente diagramma mostra come potresti visualizzare la sequenza di paragrafi nel documento precedente, ciascuno con il proprio TextRun e facoltativo Bullet impostazioni.

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

AutoText

AutoText è un ParagraphElement che rappresenta un punto nel testo sostituito dinamicamente con contenuti che possono cambiare nel tempo. In Documenti, viene utilizzato numeri di pagina.

Indici di inizio e di fine

Quando aggiorni i contenuti della scheda di un documento, ogni aggiornamento richiede posto in una posizione o in un intervallo all'interno del documento. Queste località vengono specificati utilizzando gli indici, che rappresentano un offset all'interno di un contenente il segmento del documento. Un segmento è il corpo, l'intestazione, il piè di pagina nota a piè di pagina contenente elementi strutturali o dei contenuti. Gli indici degli elementi all'interno di un segmento sono relative all'inizio di tale segmento.

La maggior parte degli elementi all'interno dei contenuti del corpo ha valori in base zero per startIndex e endIndex proprietà. Queste indicano l'offset dell'inizio 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 Batch aggiornamenti.

Gli indici vengono misurati in unità di codice UTF-16. Ciò significa che le coppie di surrogati consumano due indici. Ad esempio, "FACCIA SORVEGLIA" un'emoji, erie, è rappresentata come \uD83D\uDE00 e utilizza due indici.

Per gli elementi all'interno del corpo di un documento, gli indici rappresentano gli scostamenti dalla l'inizio del contenuto del corpo, che è la "radice" .

La sezione "Personalizzazione" per i tipi di elementi: SectionBreak, TableOfContents, Table e Paragraph: non dispongono di questi indici perché al loro interno StructuralElement contiene questi campi. Questo vale anche per la personalizzazione tipi contenuti in un ParagraphElement, ad esempio TextRun, AutoText e PageBreak.

Accedi agli elementi

Molti elementi sono modificabili con 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 lo documents.get per ottenere un Dump JSON del documento completo. Puoi quindi analizzare il file JSON risultante a trovare i valori dei singoli elementi. Per ulteriori informazioni, consulta la sezione Output i contenuti dei documenti in formato JSON.

L'analisi dei contenuti può essere utile in vari casi d'uso. Prendi in considerazione: un'applicazione di catalogazione di documenti che elenca i documenti trovati. Questa app estrarre il titolo, l'ID revisione e il numero della pagina iniziale come illustrato nel seguente diagramma:

Struttura di un catalogo di documenti.
. Figura 7. Struttura di un catalogo di documenti.

Poiché non esistono metodi per leggere esplicitamente queste impostazioni, la tua app deve per ottenere l'intero documento e quindi analizzare il codice JSON per estrarre questi valori.

Eredità della proprietà

Un StructuralElement può ereditare proprietà dagli oggetti principali. Un 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 sottolineato. La formattazione applicata sostituisce quella predefinita formattazione ereditata dalla struttura del paragrafo sottostante TextStyle Al contrario, qualsiasi i caratteri di cui non imposti una formattazione continuano a ereditare stili del paragrafo.

La formattazione del paragrafo determina il modo in cui i blocchi di testo vengono visualizzati in un documento, come allineamento, bordi e rientro. La formattazione applicata sostituisce la formattazione predefinita ereditata dall'elemento ParagraphStyle sottostante. Al contrario, le funzionalità di formattazione che non imposti continuano a ereditare come stile paragrafo.