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, lorsque la prise en charge de l'UI sera lancée, 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:
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:
Document.getTab(tabId)
: Renvoie l'onglet dont l'ID est spécifié.Document.getActiveTab()
: Affiche l'onglet actif de l'utilisateur. Fonctionne uniquement dans scripts liés à un document. La dans les sections suivantes.
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:
Document.addBookmark(position)
Document.addFooter()
Document.addHeader()
Document.addNamedRange(name, range)
Document.getBody()
Document.getBookmark(id)
Document.getBookmarks()
Document.getFooter()
Document.getFootnotes()
Document.getHeader()
Document.getNamedRangeById(id)
Document.getNamedRanges()
Document.getNamedRanges(name)
Document.newPosition(element, offset)
Document.newRange()
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:
Document.getActiveTab()
: Renvoie laTab
active de l'utilisateur dans le document actif.Document.setActiveTab(tabId)
: Définit laTab
sélectionnée par l'utilisateur dans le document actuel sur l'onglet avec le paramètre l'identifiant spécifié.
"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 des exemples 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()); } }