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:

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 de Google Docs est accessible document.tabs, qui est une liste de des objets Tab, chacun d'entre eux ; contient tous les champs de contenu textuels susmentionnés. Les sections suivantes donnent 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éder aux propriétés des onglets à l'aide de tab.tabProperties qui inclut des informations telles que l'ID, le titre et la position de l'onglet.

Accéder au contenu textuel d'un onglet

Le contenu réel du document dans l'onglet est exposé comme tab.documentTab Tous les champs de contenu textuel susmentionnés sont accessibles à l'aide de 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 activé Tab Accéder à tous les onglets d'une le document nécessite le balayage de l'arborescence d'onglets enfants. Prenons l'exemple d'une document contenant une hiérarchie d'onglets comme suit:

UI des listes d'onglets contenant trois onglets de niveau supérieur, dont certains ont des onglets enfants

Afin de récupérer le Body à partir de l'onglet 3.1.2, vous accédez 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 documents.get expose une includeTabsContent, qui permet de configurer si les contenus tous les onglets sont fournis dans la réponse.

  • Si includeTabsContent est défini sur true, le La méthode documents.get renvoie une ressource Document avec Champ document.tabs renseigné. Tous les champs de texte directement dans document (par exemple, document.body) restera vide.
  • 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 ressource Document. représentant le document vide qui a été 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.

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 Champs link.headingId dans La ressource Link ne peut plus être utilisée représenter un signet ou un titre dans 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 d'objets BookmarkLink et HeadingLink, chacun contenant l'ID du favori ou de l'en-tête, ainsi que l'ID de l'onglet dans lequel il se trouve. De plus, link.tabId expose les liens internes vers les onglets.

Lier le contenu d'une documents.get peut également varier en fonction du paramètre includeTabsContent:

  • Si includeTabsContent est défini sur true, tous les liens internes sont exposés en tant que link.bookmark et link.heading. Les anciens champs ne seront plus utilisés.
  • 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 un lien interne est créé à l'aide de l'un des anciens champs, le favori ou sera considéré comme provenant de l'identifiant de l'onglet spécifié dans le 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 de l'arborescence d'onglets, et l'appel de méthodes getter depuis Tab et DocumentTab au lieu de Document L'extrait partiel suivant l'extrait de code se base sur l'extrait Extraire le texte d'un document Émissions comment imprimer tout le contenu texte de chaque onglet d'un document. Cet onglet le code de balayage peut être adapté à de nombreux autres cas d'utilisation qui ne se soucient pas la structure réelle des onglets.

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

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

Cela revient à lire tous les onglets.

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

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 se base sur l'échantillon de Guide Insérer, supprimer et déplacer du texte

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