Utilizzare le schede

L'API Google Documenti 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 una simile alle attuali schede di Fogli. Ogni scheda ha il proprio titolo e ID (aggiunto all'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 la risorsa Document conteneva direttamente tutti i contenuti di testo tramite i seguenti campi:

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 testuali sopra menzionati. 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.

Accedere 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 in un documento richiede di attraversare l'"albero" di schede secondarie. Ad esempio, considera un documento che contiene una gerarchia di schede come la seguente:

UI dell'elenco a schede contenente tre schede di primo livello, alcune delle quali hanno schede secondarie

Per recuperare Body dalla scheda 3.1.2, accedi document.tabs[2].childTabs[0].childTabs[1].documentTab.body, Consulta i blocchi di codice di esempio nella sezione successiva, che fornisce codice di esempio per l'iterazione tra 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 su true, il valore Il metodo documents.get verrà restituito una risorsa Document con Campo document.tabs compilato. Tutti i campi di testo direttamente su document (ad es. document.body) verrà lasciato vuoto.
  • Se includeTabsContent non viene fornito, i campi di testo nella risorsa Document (ad es. document.body) verranno compilati con i contenuti solo 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. 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

Ogni 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.

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.

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

  • Se il criterio includeTabsContent viene impostato su true, tutti i link interni verranno esposti come link.bookmark e link.heading. I campi legacy 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 saranno mostrati come link.bookmark e link.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 rappresentazione JSON del 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 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();
}