L'API Google Documenti ti consente di accedere ai contenuti da qualsiasi scheda del documento.
Che cosa sono le schede?
Documenti Google presenta un livello organizzativo chiamato schede. Documenti consente agli utenti di creare una o più schede all'interno di una simile alle attuali schede di Fogli. Ogni scheda ha la sua titolo e ID (aggiunti nell'URL). Una scheda può avere anche schede secondarie, che sono schede nidificate sotto un'altra scheda.
Il supporto API per le schede secondarie è già disponibile, ma il supporto UI sarà disponibile a breve. Oggi puoi gestire le schede figlio nel tuo codice in modo che quando verrà lanciato il supporto della UI non dovrai aggiornare il codice.
Modifiche strutturali alla rappresentazione dei contenuti dei documenti nella risorsa documento
In passato, i documenti non avevano il concetto di schede, quindi
Document
Risorsa contenuta direttamente
tutto il contenuto testuale tramite i seguenti campi:
document.body
document.headers
document.footers
document.footnotes
document.documentStyle
document.suggestedDocumentStyleChanges
document.namedStyles
document.suggestedNamedStylesChanges
document.lists
document.namedRanges
document.inlineObjects
document.positionedObjects
Con l'ulteriore gerarchia strutturale delle schede, questi campi non sono più
rappresentare semanticamente i contenuti testuali di tutte le schede del documento. La
i contenuti basati su testo sono ora rappresentati in un livello diverso. Proprietà scheda e
i contenuti di Documenti Google sono accessibili tramite
document.tabs
, un elenco di
Tab
oggetti, ognuno dei quali
contiene tutti i campi di contenuti di testo indicati sopra. Le sezioni successive forniscono
una breve panoramica; il
Rappresentazione JSON delle schede
fornisce anche informazioni più dettagliate.
Accedi alle proprietà della scheda
Accedi alle proprietà della scheda utilizzando
tab.tabProperties
,
che include informazioni quali ID, titolo e posizionamento della scheda.
Accesso ai contenuti testuali di una scheda
I contenuti effettivi del documento all'interno della scheda sono visualizzati come
tab.documentTab
Tutti questi
i campi di contenuti testuali sopra indicati sono accessibili utilizzando tab.documentTab
.
Ad esempio, anziché utilizzare document.body
, devi usare
document.tabs[indexOfTab].documentTab.body
.
Gerarchia delle schede
Le schede secondarie sono rappresentate nell'API come
Campo tab.childTabs
attivato
Tab
. L'accesso a tutte le schede
documento richiede di attraversare l'"albero" di schede secondarie. Ad esempio, considera un
documento che contiene una gerarchia di schede come la seguente:
Per recuperare Body
dalla scheda 3.1.2, accedi
document.tabs[2].childTabs[0].childTabs[1].documentTab.body
, Guarda l'esempio
blocchi di codice nella sezione successiva, che fornisce un codice campione per l'iterazione
in tutte le schede di un documento.
Modifiche ai metodi
Con l'introduzione delle schede, ogni metodo dei documenti presenta alcune modifiche che potrebbero richiedere l'aggiornamento del codice.
documents.get
Per impostazione predefinita, non vengono restituiti tutti i contenuti delle schede. Gli sviluppatori devono aggiornare
per accedere a tutte le schede. La
documents.get
espone un
Parametro includeTabsContent
che consente di configurare se i contenuti vengono
tutte le schede sono fornite nella risposta.
- Se il criterio
includeTabsContent
viene impostato sutrue
, il valore Il metododocuments.get
verrà restituito una risorsaDocument
con Campodocument.tabs
compilato. Tutti i campi di testo direttamente sudocument
(ad es.document.body
) verrà lasciato vuoto. - Se
includeTabsContent
non viene fornito, i campi di testo nella risorsaDocument
(ad es.document.body
) verranno compilati con i contenuti solo della prima scheda. Il campodocument.tabs
sarà vuoto e i contenuti di altre schede non verranno restituiti.
documents.create
Il metodo documents.create
restituisce una risorsa Document
che rappresenta il documento vuoto creato. L'oggetto restituito
Document
La risorsa completerà il campo
contenuti del documento vuoti sia nei campi dei contenuti testuali del documento che
document.tabs
.
document.batchUpdate
Ciascun Request
include
un modo per specificare le schede a cui applicare l'aggiornamento. Per impostazione predefinita, se una scheda non è
specificato,
Request
nella maggior parte dei casi
applicabili alla prima scheda del documento.
ReplaceAllTextRequest
,
DeleteNamedRangeRequest
,
e
ReplaceNamedRangeContentRequest
sono tre richieste speciali che verranno applicate per impostazione predefinita a tutte le schede.
Consulta le
Request
documentazione per le specifiche.
Modifiche ai link interni
Gli utenti possono creare link interni a schede, preferiti e intestazioni di un documento.
Con l'introduzione della funzionalità delle schede, link.bookmarkId
e
link.headingId
campi nel
La risorsa Link
non può più
rappresentano un segnalibro o un'intestazione in una determinata scheda del documento.
Gli sviluppatori devono aggiornare il codice per utilizzare link.bookmark
e
link.heading
nelle operazioni di lettura e scrittura. Espongono i link interni utilizzando
BookmarkLink
e
HeadingLink
oggetti, ciascuno
contenente l'ID del preferito o dell'intestazione e l'ID della scheda in cui si trova
in. Inoltre, link.tabId
espone i link interni alle schede.
Collegare i contenuti di una documents.get
la risposta può variare anche in base al parametro includeTabsContent
:
- Se il criterio
includeTabsContent
viene impostato sutrue
, tutti i link interni verranno esposti comelink.bookmark
elink.heading
. I campi legacy non verranno più utilizzati. - Se
includeTabsContent
non viene specificato, nei documenti contenenti un valore singola scheda, eventuali link interni a preferiti o intestazioni all'interno della scheda singola continuano a essere esposte comelink.bookmarkId
elink.headingId
. Nei documenti contenente più schede, i link interni saranno mostrati comelink.bookmark
elink.heading
.
In document.batchUpdate
,
se viene creato un link interno utilizzando uno dei campi precedenti, il segnalibro o
verrà considerata come proveniente dall'ID scheda specificato in
Request
. Se non viene visualizzata alcuna scheda
specificato, verrà considerata come proveniente dalla prima scheda del documento.
La La rappresentazione JSON dei link fornisce informazioni più dettagliate.
Modelli di utilizzo comuni per le schede
I seguenti esempi di codice descrivono le varie modalità di interazione con le schede.
Leggi i contenuti delle schede di tutte le schede del documento
Il codice esistente che ha eseguito questa operazione prima della migrazione della funzionalità delle schede all'assistenza
impostando il parametro includeTabsContent
su true
, attraversando
la gerarchia ad albero delle schede e richiamare metodi getter
Tab
e
DocumentTab
invece di
Document
La seguente parte
l'esempio di codice si basa sullo snippet
Estrai il testo da un documento. Mostra
come stampare tutti i contenuti di testo da ogni scheda di un documento. Questa scheda
il codice di attraversamento può essere adattato per molti altri casi d'uso che non
la struttura effettiva delle schede.
Java
/** Prints all text contents from all tabs in the document. */ static void printAllText(Docs service, String documentId) throws IOException { // Fetch the document with all of the tabs populated, including any nested // child tabs. Document doc = service.documents().get(documentId).setIncludeTabsContent(true).execute(); List<Tab> allTabs = getAllTabs(doc); // Print the content from each tab in the document. for (Tab tab: allTabs) { // Get the DocumentTab from the generic Tab. DocumentTab documentTab = tab.getDocumentTab(); System.out.println( readStructuralElements(documentTab.getBody().getContent())); } } /** * Returns a flat list of all tabs in the document in the order they would * appear in the UI (top-down ordering). Includes all child tabs. */ private List<Tab> getAllTabs(Document doc) { List<Tab> allTabs = new ArrayList<>(); // Iterate over all tabs and recursively add any child tabs to generate a // flat list of Tabs. for (Tab tab: doc.getTabs()) { addCurrentAndChildTabs(tab, allTabs); } return allTabs; } /** * Adds the provided tab to the list of all tabs, and recurses through and * adds all child tabs. */ private void addCurrentAndChildTabs(Tab tab, List<Tab> allTabs) { allTabs.add(tab); for (Tab tab: tab.getChildTabs()) { addCurrentAndChildTabs(tab, allTabs); } } /** * Recurses through a list of Structural Elements to read a document's text * where text may be in nested elements. * * <p>For a code sample, see * <a href="https://developers.google.com/docs/api/samples/extract-text">Extract * the text from a document</a>. */ private static String readStructuralElements(List<StructuralElement> elements) { ... }
Leggi i contenuti della scheda dalla prima scheda nel documento
Questa operazione è simile alla lettura di tutte le schede.
Java
/** Prints all text contents from the first tab in the document. */ static void printAllText(Docs service, String documentId) throws IOException { // Fetch the document with all of the tabs populated, including any nested // child tabs. Document doc = service.documents().get(documentId).setIncludeTabsContent(true).execute(); List<Tab> allTabs = getAllTabs(doc); // Print the content from the first tab in the document. Tab firstTab = allTabs.get(0); // Get the DocumentTab from the generic Tab. DocumentTab documentTab = firstTab.getDocumentTab(); System.out.println( readStructuralElements(documentTab.getBody().getContent())); }
Invia una richiesta di aggiornamento della prima scheda
Il seguente esempio di codice parziale mostra come scegliere come target una scheda specifica in un
Request
Questo codice
si basa sul campione
Guida all'inserimento, all'eliminazione e allo spostamento di testo.
Java
/** Inserts text into the first tab of the document. */ static void insertTextInFirstTab(Docs service, String documentId) throws IOException { // Get the first tab's ID. Document doc = service.documents().get(documentId).setIncludeTabsContent(true).execute(); Tab firstTab = doc.getTabs().get(0); String tabId = firstTab.getTabProperties().getTabId(); List<Request>requests = new ArrayList<>(); requests.add(new Request().setInsertText( new InsertTextRequest().setText(text).setLocation(new Location() // Set the tab ID. .setTabId(tabId) .setIndex(25)))); BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest().setRequests(requests); BatchUpdateDocumentResponse response = docsService.documents().batchUpdate(DOCUMENT_ID, body).execute(); }