Utiliser les onglets

Apps Script pour Google Docs vous permet d'accéder au contenu dans le document.

Que sont les onglets ?

Google Docs comporte une couche organisationnelle appelée onglets. Documents permet aux utilisateurs de créer un ou plusieurs onglets dans un même document, de la même manière que il y a aujourd'hui des onglets dans Sheets. Chaque onglet a son propre titre et un identifiant (ajouté dans l'URL). Un onglet peut également comporter des onglets enfants, c'est-à-dire des onglets imbriqués 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, une fois la prise en charge de l'UI prise en charge vous n'aurez pas à mettre à jour d'autres codes.

Accéder aux onglets

Les propriétés et le contenu des onglets sont accessibles via Document.getTabs(), qui renvoie une liste de Tab. Les sections suivantes présentent brièvement les Classe Tab ; la documentation sur la classe d'onglet 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 de l'onglet

Le contenu des documents dans chaque onglet peut être récupéré à l'aide de Tab.asDocumentTab() Modifications apportées à la structure de la classe Document décrit comment cela peut être utilisé.

Hiérarchie des onglets

Les onglets enfants sont exposés dans Google Apps Script via Tab.getChildTabs() Pour accéder au contenu de tous les onglets, vous devez parcourir l'arborescence. d'onglets enfants. Prenons l'exemple d'un document qui contient une hiérarchie d'onglets comme suit:

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

Pour accéder à l'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());

Vous trouverez des exemples de blocs de code dans les sections suivantes. Vous y trouverez des exemples de code pour l’itération dans 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 les onglets:

Modifications apportées à la structure de la classe Document

Auparavant, le concept d'onglet n'existait pas dans les documents. La classe Document méthodes exposées pour accéder directement au contenu textuel du document et le modifier. Les méthodes suivantes appartiennent à cette catégorie:

Avec la hiérarchie structurelle supplémentaire des onglets, ces méthodes ne sont plus représenter sémantiquement le contenu textuel de tous les onglets du document. Le texte le contenu sera représenté dans une couche différente, tous les éléments susmentionnés les méthodes de texte sont accessibles via DocumentTab.

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

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 en dehors de la classe DocumentTab (qui est disponibles via la Tab.asDocumentTab() ). 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

Méthodes de sélection de texte

La classe Document fournit des getters et des setters pour gérer leur emplacement dans le 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(position): Définit la position du curseur de l'utilisateur dans le document actif. Si la position se trouve dans une onglet inactif, l'onglet actif de l'utilisateur est également basculé vers l'onglet associé pour ce poste.
  • Document.setSelection(range): Définit la plage de sélection de l'utilisateur dans le document actif. Si la plage est dans un onglet inactif, l'onglet actif de l'utilisateur est également basculé vers l'onglet associé avec cette plage.

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

Avec l'introduction des onglets, il peut être utile d'obtenir et de définir l'onglet actif de l'utilisateur qui exécute le script. Pour ce faire, vous pouvez utiliser les méthodes suivantes:

"Sélection" globale de l'utilisateur est composé d'une combinaison de l'onglet actif ainsi que la position actuelle du curseur ou la plage de sélection. Les deux des modèles d'utilisation d'une sélection active consiste à modifier explicitement l'onglet actif de l'utilisateur vers un onglet spécifique ou utiliser l'onglet actif de l'utilisateur.

Vous pouvez modifier explicitement l'onglet actif de l'utilisateur en utilisant Document.setActiveTab(tabId) Vous pouvez également appeler Document.setCursor(position) ou Document.setSelection(range) comportant un Position ou Range d'un onglet inactif, actif.

Si le script prévoit d'utiliser l'onglet actif de l'utilisateur sans la modifier, puis Document.setActiveTab(tabId) n'est pas nécessaire. La Document.getCursor() et Document.getSelection() méthodes fonctionnent déjà sur l'onglet actif, en fonction de l'onglet auquel depuis lequel l'utilisateur exécute le script.

Notez qu'un document ne prend pas en charge plusieurs sélections d'onglets ou ou plages supplémentaires dans les différents onglets. Par conséquent, l'utilisation Document.setActiveTab(tabId) effacera 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 est ce qui donne un sens aux concepts de sélection de texte de Position et Range. En d'autres termes, une position de curseur ou une plage de sélection ne sont significatives que si le script connaît l'onglet spécifique auquel la position ou se situe dans cette plage.

Pour ce faire, vous pouvez utiliser DocumentTab.newPosition(element, offset) et DocumentTab.newRange() qui construisent une position ou une plage qui cible DocumentTab à partir duquel la méthode est appelée. En revanche, Document.newPosition(element, offset) et Document.newRange() créera une position ou une plage qui cible l'onglet actif (ou le premier , si le script n'est pas lié).

Vous trouverez des exemples de blocs de code dans les sections suivantes. Vous y trouverez un exemple de code pour travailler avec les sélections.

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 balayant l'arborescence d'onglets et en appelant les méthodes getter de Tab et DocumentTab au lieu de Document. L'exemple de code partiel suivant montre comment pour 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.

/** 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 de l'onglet du premier onglet du document

Cela revient à lire 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 de l'onglet dans le premier onglet

L'exemple de code partiel suivant montre comment cibler un onglet spécifique lorsque vous créez mises à 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 lorsque vous effectuez mises à 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. Ceci n'est pertinent que dans les scripts.

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