Utiliser les onglets

Google Apps Script pour Google Docs vous permet d'accéder au contenu de n'importe quel onglet du document.

Que sont les onglets ?

Docs comporte une couche organisationnelle appelée onglets. Docs permet aux utilisateurs de créer un ou plusieurs onglets dans un même document, comme c'est le cas aujourd'hui dans Sheets. Chaque onglet possède son propre titre et un ID (ajouté à l'URL). Un onglet peut également comporter des onglets enfants, qui sont des onglets imbriqués sous un autre onglet.

Accéder aux onglets

Les propriétés et le contenu des onglets sont accessibles avec Document.getTabs, qui renvoie une liste de Tab. Les sections suivantes présentent brièvement la classe Tab. La documentation de la classe Tab fournit également des informations plus détaillées.

Propriétés des onglets

Les propriétés des onglets peuvent être récupérées à l'aide de méthodes telles que Tab.getId et Tab.getTitle.

Contenu des onglets

Le contenu du document dans chaque onglet peut être récupéré à l'aide de Tab.asDocumentTab. La section Modifications apportées à la structure de la classe Document décrit comment l'utiliser.

Hiérarchie des onglets

Les onglets enfants sont exposés dans Apps Script via Tab.getChildTabs. Pour accéder au contenu de tous les onglets, vous devez parcourir l'arborescence des onglets enfants. Par exemple, considérons un document contenant une hiérarchie d'onglets comme suit :

Interface utilisateur de liste d'onglets contenant trois onglets de premier niveau, dont certains comportent des onglets enfants

Pour accéder à Onglet 3.1.2, procédez comme suit :

// Print the ID of Tab 3.1.2.
const doc = DocumentApp.getActiveDocument();
const tab = doc.getTabs()[2].getChildTabs()[0].getChildTabs()[1];
console.log(tab.getId());

Consultez les blocs d'exemples de code dans les sections suivantes pour obtenir un exemple de code qui itère sur tous les onglets d'un document.

Autres façons de récupérer des onglets

Il existe deux autres façons de récupérer des onglets :

  • Document.getTab: renvoie l'onglet avec l'ID spécifié.
  • Document.getActiveTab: renvoie l'onglet actif de l'utilisateur. Ne fonctionne que dans les scripts liés à un document. Les sections suivantes décrivent cela plus en détail.

Modifications apportées à la structure de la classe Document

Auparavant, les documents ne comportaient pas d'onglets. La classe Document exposait donc des méthodes permettant d'accéder directement au contenu textuel du document et de le modifier. Les méthodes suivantes appartiennent à cette catégorie :

Avec la hiérarchie structurelle supplémentaire des onglets, ces méthodes ne représentent plus sémantiquement le contenu textuel de tous les onglets du document. Le contenu textuel sera désormais représenté dans une autre couche. Toutes les méthodes de texte mentionnées ci-dessus sont accessibles via DocumentTab.

Ces méthodes existantes de la classe Document accèdent au contenu de l'onglet actif (dans les scripts liés à un document particulier) ou du premier onglet (si aucun onglet actif n'est disponible) ou le modifient.

Accéder au contenu textuel d'un onglet spécifique

Au lieu d'utiliser les méthodes de texte de Document, il est recommandé d'utiliser les méthodes disponibles dans la classe DocumentTab (disponible via la Tab.asDocumentTab méthode). Exemple :

// Print the text from the body of the active tab.
const doc = DocumentApp.getActiveDocument();
const documentTab = doc.getActiveTab().asDocumentTab();
const body = documentTab.getBody();
console.log(body.getText());

Modifications apportées à la sélection de l'utilisateur

Le concept de sélection de l'utilisateur n'est pertinent et ne peut être utilisé ou modifié que par des scripts qui sont liés à un document.

Méthodes de sélection de texte

La classe Document fournit des getters et des setters pour gérer l'emplacement du texte que l'utilisateur sélectionne dans le document actif. Ces méthodes fonctionnent dans le contexte de l'onglet actif de l'utilisateur qui exécute le script.

  • Document.getCursor: renvoie la position du curseur de l'utilisateur dans l'onglet actif.
  • Document.getSelection: renvoie la plage de sélection de l'utilisateur dans l'onglet actif.
  • Document.setCursor: définit la position du curseur de l'utilisateur dans le document actif. Si la position se trouve dans un onglet inactif, l'onglet actif de l'utilisateur est également remplacé par l'onglet associé à cette position.
  • Document.setSelection: définit la plage de sélection de l'utilisateur dans le document actif. Si la plage se trouve dans un onglet inactif, l'onglet actif de l'utilisateur est également remplacé par l'onglet associé à cette plage.

Méthodes de sélection d'onglets et cas d'utilisation

Avec l'introduction des onglets, obtenez et définissez l'onglet actif de l'utilisateur qui exécute le script. Utilisez les méthodes suivantes :

  • Document.getActiveTab : renvoie l'élément Tab actif de l'utilisateur dans le document actif.
  • Document.setActiveTab : définit l'onglet Tab sélectionné par l'utilisateur dans le document actuel sur l'onglet avec l' ID spécifié.

La "sélection" globale de l'utilisateur est constituée d'une combinaison de l'onglet actif et de la position actuelle du curseur ou de la plage de sélection. Les deux modèles d'utilisation d'une sélection active consistent à modifier explicitement l'onglet actif de l'utilisateur en un onglet spécifique ou à utiliser l'onglet actif de l'utilisateur.

Modifiez explicitement l'onglet actif de l'utilisateur à l'aide de Document.setActiveTab. Vous pouvez également appeler Document.setCursor ou Document.setSelection avec une Position ou une Range à partir d'un onglet inactif pour rendre cet onglet actif.

Si le comportement prévu du script consiste à utiliser l'onglet actif de l'utilisateur sans le modifier, alors Document.setActiveTab n'est pas nécessaire. Les méthodes Document.getCursor et Document.getSelection fonctionnent sur l'onglet actif, en fonction de l'onglet à partir duquel l'utilisateur exécute le script.

Un document ne permet pas de sélectionner plusieurs onglets, ni plusieurs positions ou plages dans différents onglets. Par conséquent, l'utilisation de Document.setActiveTab efface la position précédente du curseur ou la plage de sélection.

Méthodes de position et de plage pour un onglet spécifique

L'onglet spécifique donne un sens aux concepts de sélection de texte Position et Range. Une position de curseur ou une plage de sélection n'est significative que si le script connaît l'onglet spécifique dans lequel se trouve la position ou la plage.

Pour ce faire, utilisez les DocumentTab.newPosition et DocumentTab.newRange méthodes, qui construisent une position ou une plage ciblant le DocumentTab spécifique à partir duquel la méthode est appelée. En revanche, Document.newPosition et Document.newRange construisent une position ou une plage dans l'onglet actif (ou le premier onglet, si le script n'est pas lié).

Consultez les blocs d'exemples de code dans les sections suivantes pour obtenir un exemple de code permettant d'utiliser des sélections.

Modèles d'utilisation courants pour les onglets

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

Lire le contenu de tous les onglets du document

Le code existant qui effectuait cette opération avant la fonctionnalité des onglets peut être migré pour prendre en charge les onglets en parcourant l'arborescence des onglets et en appelant les méthodes getter de Tab et DocumentTab au lieu de Document. L'exemple de code partiel suivant montre comment imprimer tout le contenu textuel de chaque onglet d'un document. Ce code de parcours d'onglets peut être adapté à de nombreux autres cas d'utilisation qui ne se soucient pas de la structure réelle des onglets.

/** Logs all text contents from all tabs in the active document. */
function logAllText() {
  // Generate a list of all the tabs in the document, including any
  // nested child tabs. DocumentApp.openById('abc123456') can also
  // be used instead of DocumentApp.getActiveDocument().
  const doc = DocumentApp.getActiveDocument();
  const allTabs = getAllTabs(doc);

  // Log the content from each tab in the document.
  for (const tab of allTabs) {
    // Get the DocumentTab from the generic Tab object.
    const documentTab = tab.asDocumentTab();
    // Get the body from the given DocumentTab.
    const body = documentTab.getBody();
    // Get the body text and log it to the console.
    console.log(body.getText());
  }
}

/**
 * Returns a flat list of all tabs in the document, in the order
 * they would appear in the UI (i.e. top-down ordering). Includes
 * all child tabs.
 */
function getAllTabs(doc) {
  const allTabs = [];
  // Iterate over all tabs and recursively add any child tabs to
  // generate a flat list of Tabs.
  for (const tab of 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.
 */
function addCurrentAndChildTabs(tab, allTabs) {
  allTabs.push(tab);
  for (const childTab of tab.getChildTabs()) {
    addCurrentAndChildTabs(childTab, allTabs);
  }
}

Lire le contenu du premier onglet du document

Cette opération est semblable à la lecture de tous les onglets.

/** 
 * Logs all text contents from the first tab in the active 
 * document. 
 */
function logAllText() {
  // Generate a list of all the tabs in the document, including any
  // nested child tabs.
  const doc = DocumentApp.getActiveDocument();
  const allTabs = getAllTabs(doc);

  // Log the content from the first tab in the document.
  const firstTab = allTabs[0];
  // Get the DocumentTab from the generic Tab object.
  const documentTab = firstTab.asDocumentTab();
  // Get the body from the DocumentTab.
  const body = documentTab.getBody();
  // Get the body text and log it to the console.
  console.log(body.getText());
}

Mettre à jour le contenu du premier onglet

L'exemple de code partiel suivant montre comment cibler un onglet spécifique lors de la mise à jour.

/** Inserts text into the first tab of the active document. */
function insertTextInFirstTab() {
  // Get the first tab's body.
  const doc = DocumentApp.getActiveDocument();
  const firstTab = doc.getTabs()[0];
  const firstDocumentTab = firstTab.asDocumentTab();
  const firstTabBody = firstDocumentTab.getBody();

  // Append a paragraph and a page break to the first tab's body
  // section.
  firstTabBody.appendParagraph("A paragraph.");
  firstTabBody.appendPageBreak();
}

Mettre à jour le contenu de l'onglet actif ou sélectionné

L'exemple de code partiel suivant montre comment cibler l'onglet actif lors de la mise à jour.

/**
 * Inserts text into the active/selected tab of the active
 * document.
 */
function insertTextInActiveTab() {
  // Get the active/selected tab's body.
  const doc = DocumentApp.getActiveDocument();
  const activeTab = doc.getActiveTab();
  const activeDocumentTab = activeTab.asDocumentTab();
  const activeTabBody = activeDocumentTab.getBody();

  // Append a paragraph and a page break to the active tab's body
  // section.
  activeTabBody.appendParagraph("A paragraph.");
  activeTabBody.appendPageBreak();
}

Définir une position de curseur ou une plage de sélection dans l'onglet actif

L'exemple de code partiel suivant montre comment mettre à jour la position du curseur ou la plage de sélection dans l'onglet actif de l'utilisateur. Cela n'est pertinent que dans les scripts liés.

/**
 * Changes the user's selection to select all tables within the tab
 * with the provided ID.
 */
function selectAllTables(tabId) {
  const doc = DocumentApp.getActiveDocument();
  const tab = doc.getTab(tabId);
  const documentTab = tab.asDocumentTab();

  // Build a range that encompasses all tables within the specified
  // tab.
  const rangeBuilder = documentTab.newRange();
  const tables = documentTab.getBody().getTables();
  for (let i = 0; i < tables.length; i++) {
    rangeBuilder.addElement(tables[i]);
  }
  // Set the document's selection to the tables within the specified
  // tab. Note that this actually switches the user's active tab as
  // well.
  doc.setSelection(rangeBuilder.build());
}

Définir l'onglet actif ou sélectionné

L'exemple de code partiel suivant montre comment modifier l'onglet actif de l'utilisateur. Cela n'est pertinent que dans les scripts liés.

/**
 * Changes the user's selected tab to the tab immediately following
 * the currently selected one. Handles child tabs.
 *
 * 
Only changes the selection if there is a tab following the
 * currently selected one.
 */
function selectNextTab() {
  const doc = DocumentApp.getActiveDocument();
  const allTabs = getAllTabs(doc);
  const activeTab = doc.getActiveTab();

  // Find the index of the currently active tab.
  let activeTabIndex = -1;
  for (let i = 0; i < allTabs.length; i++) {
    if (allTabs[i].getId() === activeTab.getId()) {
      activeTabIndex = i;
    }
  }

  // Update the user's selected tab if there is a valid next tab.
  const nextTabIndex = activeTabIndex + 1;
  if (nextTabIndex < allTabs.length) {
    doc.setActiveTab(allTabs[nextTabIndex].getId());
  }
}