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
contenuti in Documenti Google sono accessibili tramite documents.tabs
, che è un elenco
di Tabs
, ognuno dei quali contiene tutti i campi di contenuti testuali 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 come
come 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
dei campi di contenuti testuali citati in precedenza sono accessibili tramite
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
su Tab
.
L'accesso a tutte le schede di un documento richiede di attraversare la "struttura ad albero" di schede secondarie.
Ad esempio, considera un documento che contiene una gerarchia di schede come segue:
Per recuperare body
dalla Scheda 3.1.2, devi accedere
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. Il metodo documents.get
espone una
Parametro includeTabsContent
che consente di configurare se i contenuti vengono
tutte le schede sono fornite nella risposta.
- Se
includeTabsContent
è impostato sutrue
, il metododocuments.get
restituirà una risorsaDocument
con il campodocument.tabs
compilato. Tutti i campi di testo direttamente indocument
(ad es.document.body
) verranno lasciati vuoti. - 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 un
Document
Risorsa che rappresenta la
è stato creato un documento vuoto. 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
I campi link.headingId
non possono più rappresentare un preferito o un'intestazione in una
una particolare 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.
Anche i contenuti dei link di una risposta documents.get
possono variare in base al
Parametro includeTabsContent
:
- Se il criterio
includeTabsContent
viene impostato sutrue
, tutti i link interni verranno esposti comelink.bookmark
elink.heading
. Campi legacy (link.bookmarkId
elink.headingId
) 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 preferito o l'intestazione verranno considerati come provenienti dall'ID scheda
specificato nel
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
È possibile eseguire la migrazione del codice esistente che ha eseguito questa operazione prima della funzionalità delle schede per l'assistenza
impostando il parametro IncludeTabsContent
su true
, attraversando
gerarchia ad albero di schede e chiamata a metodi getter da Tab
e DocumentTab
anziché
Document
.
Il seguente esempio di codice parziale si basa sullo snippet in
Estrai il testo da un documento.
Mostra come stampare tutti i contenuti di testo da ogni scheda di un documento.
Questo codice di attraversamento delle schede 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 è basato sull'esempio nel campo
Inserire, eliminare e spostare testo
Guida.
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(); }