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 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:

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, 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 su true, il metodo documents.get restituirà una risorsa Document con il campo document.tabs compilato. Tutti i campi di testo direttamente in document (ad es. document.body) verranno lasciati vuoti.
  • 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 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.

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 su true, tutti i link interni verranno esposti come link.bookmark e link.heading. Campi legacy (link.bookmarkId e link.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 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 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();
}