Utiliser les onglets

L'API Google Docs vous permet d'accéder au contenu de n'importe quel onglet du document.

Que sont les onglets ?

Google Docs comporte une couche organisationnelle appelée onglets. Docs permet aux utilisateurs de créer un ou plusieurs onglets dans un même de façon similaire à ce qu'il y a d'onglets dans Sheets aujourd'hui. Chaque onglet a son propre titre et l'ID (ajoutés à l'URL). Un onglet peut également comporter des onglets enfants, sous un autre onglet.

L'API prend en charge les onglets enfants dès aujourd'hui, mais elle sera bientôt compatible avec l'interface utilisateur. Aujourd'hui, vous pouvez gérer les onglets enfants dans votre code. Ainsi, lorsque la prise en charge de l'UI sera lancée, vous n'aurez pas à mettre à jour d'autres codes.

Modifications structurelles de la représentation du contenu du document dans la ressource Document

Auparavant, le concept d'onglet n'existait pas dans les documents. Document Ressource directement contenue tout le contenu textuel dans les champs suivants:

• document.body
• document.headers
• document.footers
• document.footnotes
• document.documentStyle
• document.suggestedDocumentStyleChanges
• document.namedStyles
• document.suggestedNamedStylesChanges
• document.lists
• document.namedRanges
• document.inlineObjects
• document.positionedObjects

Avec la hiérarchie structurelle supplémentaire des onglets, ces champs ne sont plus représenter sémantiquement le contenu textuel de tous les onglets du document. La le contenu textuel est maintenant représenté dans une autre couche. Propriétés des onglets et le contenu dans Google Docs est accessible via la liste documents.tabs de Tabs, chacun contenant tous les champs de contenu textuel susmentionnés. Les sections suivantes offrent un bref aperçu : la Représentation JSON des onglets fournit également des informations plus détaillées.

Accéder aux propriétés de l'onglet

Accédez aux propriétés des onglets à l'aide de tab.tabProperties, qui inclut des informations telles que comme l'ID, le titre et le positionnement de l'onglet.

Accéder au contenu textuel d'un onglet

Le contenu réel du document dans l'onglet est affiché en tant que tab.documentTab. Tout des champs de contenu textuels susmentionnés sont accessibles tab.documentTab Par exemple, au lieu d'utiliser document.body, vous devez utiliser document.tabs[indexOfTab].documentTab.body

Hiérarchie des onglets

Dans l'API, les onglets enfants sont représentés par un champ tab.childTabs sur Tab. Pour accéder à tous les onglets d'un document, vous devez parcourir l'arborescence. d'onglets enfants. Prenons l'exemple d'un document qui contient une hiérarchie d'onglets comme suit:

Pour récupérer le body à partir de l'onglet 3.1.2, vous devez utiliser document.tabs[2].childTabs[0].childTabs[1].documentTab.body Voir l'exemple dans la section suivante, qui fournit un exemple de code pour l'itération dans tous les onglets d'un document.

Modifications apportées aux méthodes

Avec l'introduction des onglets, chacune des méthodes de document comporte quelques modifications qui peuvent vous obliger à mettre à jour votre code.

documents.get

Par défaut, tout le contenu des onglets n'est pas renvoyé. Les développeurs doivent mettre à jour pour accéder à tous les onglets. La méthode documents.get expose une Le paramètre includeTabsContent, qui permet de configurer si les contenus tous les onglets sont fournis dans la réponse.

• Si includeTabsContent est défini sur true, la méthode documents.get renvoie une ressource Document avec le champ document.tabs renseigné. Tous les champs de texte situés directement dans document (par exemple, document.body) resteront vides.
• Si includeTabsContent n'est pas fourni, les champs de texte de la ressource Document (par exemple, document.body) seront renseignés avec le contenu du premier onglet uniquement. Le champ document.tabs sera vide et le contenu des autres onglets ne sera pas renvoyé.

documents.create

La méthode documents.create renvoie une Document Ressource représentant la un document vide créé. La valeur renvoyée Document La ressource insère le contenu vide du document dans les champs de contenu textuel du document ainsi que document.tabs

document.batchUpdate

Chaque Request inclut un moyen de spécifier les onglets auxquels appliquer la mise à jour. Par défaut, si un onglet n'est pas est spécifiée, la valeur Request va dans la plupart des cas les cas s'appliquent au premier onglet du document. ReplaceAllTextRequest, DeleteNamedRangeRequest, et ReplaceNamedRangeContentRequest il y a trois demandes spéciales qui s'appliqueront par défaut à tous les onglets.

Consultez le Requests dans la documentation Google Cloud Platform.

Modifications apportées aux liens internes

Les utilisateurs peuvent créer des liens internes vers les onglets, les favoris et les en-têtes d'un document. Avec le lancement des onglets, les options link.bookmarkId et Les champs link.headingId ne peuvent plus représenter un favori ni un titre dans une un onglet particulier du document.

Les développeurs doivent mettre à jour leur code pour utiliser link.bookmark et link.heading dans les opérations de lecture et d'écriture. Ils exposent des liens internes à l'aide de BookmarkLink et Objets HeadingLink chacun contenant l'ID du favori ou du titre et l'ID de l'onglet dans lequel il se trouve po. De plus, link.tabId expose les liens internes vers les onglets.

Le contenu d'un lien dans une réponse documents.get peut également varier en fonction de la Paramètre includeTabsContent:

• Si includeTabsContent est défini sur true, tous les liens internes seront exposés. en tant que link.bookmark et link.heading. Anciens champs (link.bookmarkId et link.headingId) ne sera plus utilisée.
• Si includeTabsContent n'est pas fourni, alors dans les documents contenant un un seul onglet, tout lien interne vers des favoris ou des titres dans cet onglet unique continuent d'être exposés sous les noms link.bookmarkId et link.headingId. Dans les documents contenant plusieurs onglets, les liens internes seront affichés sous la forme link.bookmark et link.heading

Dans document.batchUpdate, si une association interne est créée à l'aide de l'un des anciens champs, le favori ou l'en-tête sera considéré comme provenant de l'ID de l'onglet spécifiées dans Request Si aucun onglet n'est spécifié, il sera considéré comme provenant du premier onglet du document.

La La représentation JSON du lien permet des informations plus détaillées.

Schémas d'utilisation courants des onglets

Les exemples de code suivants décrivent différentes façons d'interagir avec les onglets.

Lire le contenu des onglets de tous les onglets du document

Le code existant qui effectuait cette opération avant que la fonctionnalité des onglets puisse être migrée vers la prise en charge en définissant le paramètre IncludeTabsContent sur true, en balayant hiérarchie de l'arborescence d'onglets, et appel de méthodes getter à partir de Tab et DocumentTab au lieu de Document L'exemple de code partiel suivant est basé sur l'extrait de code situé à l'adresse Extraire le texte d'un document Il montre comment imprimer tout le contenu texte de chaque onglet d'un document. Ce code de balayage d'onglet peut être adapté à de nombreux autres cas d'utilisation qui ne nécessitent pas vous soucier de la structure réelle des onglets.

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

Lire le contenu de l'onglet du premier onglet du document

Cela revient à lire tous les onglets.

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

Envoyer une requête pour mettre à jour le premier onglet

L'exemple de code partiel suivant montre comment cibler un onglet spécifique dans un Request Ce code est basé sur l'exemple de la section Insérer, supprimer et déplacer du texte Guide de démarrage.

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