Lavorare con le schede

L'API Documenti Google ti consente di accedere ai contenuti da qualsiasi scheda del documento.

Che cosa sono le schede?

Documenti Google dispone di un livello di organizzazione chiamato schede. Documenti consente agli utenti di creare una o più schede all'interno di un singolo documento, in modo simile a come sono presenti le schede in Fogli oggi. Ogni scheda ha il proprio titolo e ID (aggiunto all'URL). Una scheda può avere anche schede secondarie, ovvero schede nidificate sotto un'altra scheda.

Modifiche strutturali alla modalità di rappresentazione dei contenuti dei documenti nella risorsa documento

In passato, i documenti non avevano un concetto di schede, pertanto la risorsa Document conteneva direttamente tutti i contenuti di testo 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 la gerarchia strutturale aggiuntiva delle schede, questi campi non rappresentano più semanticamente i contenuti di testo di tutte le schede del documento. I contenuti basati su testo ora sono rappresentati in un livello diverso. Le proprietà e i contenuti delle schede in Documenti Google sono accessibili con document.tabs, che è un elenco di oggetti Tab, ciascuno dei quali contiene tutti i campi di contenuti di testo sopra menzionati. Le sezioni successive forniscono una breve panoramica. La rappresentazione JSON della scheda fornisce anche informazioni più dettagliate.

Accedere alle proprietà della scheda

Accedi alle proprietà della scheda utilizzando tab.tabProperties, che include informazioni quali l'ID, il titolo e il posizionamento della scheda.

Accedere ai contenuti di testo all'interno di una scheda

I contenuti effettivi del documento all'interno della scheda vengono esposti come tab.documentTab. Tutti i campi di contenuti di testo sopra menzionati sono accessibili utilizzando tab.documentTab. Ad esempio, anziché utilizzare document.body, dovresti utilizzare document.tabs[indexOfTab].documentTab.body.

Gerarchia delle schede

Le schede secondarie sono rappresentate nell'API come un campo tab.childTabs in Tab. Per accedere a tutte le schede di un documento è necessario attraversare la "struttura ad albero" delle 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. Consulta i blocchi di codice di esempio nella sezione successiva, che forniscono codice di esempio per l'iterazione su tutte le schede di un documento.

Modifiche ai metodi

Con l'introduzione delle schede, ciascuno dei metodi del documento 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 il codice per accedere a tutte le schede. Il metodo documents.get espone un parametro includeTabsContent che consente di configurare se i contenuti di tutte le schede devono essere forniti nella risposta.

• Se includeTabsContent è impostato su true, il metodo documents.get restituirà una risorsa Document con il campo document.tabs compilato. Tutti i campi di testo direttamente su document (ad es. document.body) verranno lasciati vuoti.
• Se non viene fornito includeTabsContent, i campi di testo nella risorsa Document (ad es. document.body) verranno compilati solo con i contenuti della prima scheda. Il campo document.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. La risorsa Document restituita completerà i contenuti del documento vuoti sia nei campi dei contenuti di testo del documento sia in document.tabs.

document.batchUpdate

Ogni Request include un modo per specificare le schede a cui applicare l'aggiornamento. Per impostazione predefinita, se non viene specificata una scheda, in genere il carattere Request viene applicato alla prima scheda del documento. ReplaceAllTextRequest, DeleteNamedRangeRequest, e ReplaceNamedRangeContentRequest sono tre richieste speciali che per impostazione predefinita verranno applicate a tutte le schede.

Per informazioni specifiche, consulta la documentazione di Request.

Modifiche ai link interni

Gli utenti possono creare link interni a schede, preferiti e intestazioni in un documento. Con l'introduzione della funzionalità delle schede, i campi link.bookmarkId e link.headingId nella risorsa Link non possono più rappresentare un preferito 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 gli oggetti BookmarkLink e HeadingLink, ciascuno contenente l'ID del preferito o dell'intestazione e l'ID della scheda in cui si trova. Inoltre, link.tabId mostra i link interni alle schede.

I contenuti dei link di una risposta documents.get possono variare anche in base al parametro includeTabsContent:

• Se includeTabsContent è impostato su true, tutti i link interni verranno esposti come link.bookmark e link.heading. I campi precedenti non verranno più utilizzati.
• Se non viene fornito includeTabsContent, nei documenti contenenti una singola scheda, eventuali link interni a preferiti o intestazioni all'interno di quella singola scheda continuano a essere esposti come link.bookmarkId e link.headingId. Nei documenti contenente più schede, i link interni verranno esposti come link.bookmark e link.heading.

In document.batchUpdate, se viene creato un link interno utilizzando uno dei campi precedenti, il segnalibro o l'intestazione verrà considerato proveniente dall'ID scheda specificato in Request. Se non viene specificata alcuna scheda, verrà considerata la prima scheda del documento.

La rappresentazione JSON del link fornisce informazioni più dettagliate.

Pattern di utilizzo comuni per le schede

I seguenti esempi di codice descrivono diversi modi per interagire con le schede.

Leggere i contenuti di tutte le schede del documento

È possibile eseguire la migrazione del codice esistente che eseguiva questa operazione prima della funzionalità delle schede impostando il parametro includeTabsContent su true, attraversando la gerarchia ad albero delle schede e chiamando i metodi getter di Tab e DocumentTab anziché Document. Il seguente esempio di codice parziale si basa sullo snippet riportato in Estrarre il testo da un documento. Mostra come stampare tutti i contenuti di testo di ogni scheda di un documento. Questo codice di traversale delle schede può essere adattato a molti altri casi d'uso che non richiedono la struttura effettiva delle schede.

/** 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) {
  ...
}

Leggere i contenuti della prima scheda del documento

È simile alla lettura di tutte le schede.

/** 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()));
}

Fai una richiesta per aggiornare la prima scheda

Il seguente esempio di codice parziale mostra come scegliere come target una scheda specifica in un Request. Questo codice è basato sull'esempio riportato nella guida Inserire, eliminare e spostare il testo.

/** 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();
}