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
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.
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:
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:
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
terminando 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 la specifica del container.
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:
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 di seguito.
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:
Il seguente diagramma mostra come potresti visualizzare la sequenza di paragrafi
nel documento precedente, ciascuno con il proprio TextRun e facoltativo Bullet
impostazioni.
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 struttura
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:
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.