Pour utiliser efficacement l'API Google Docs, vous devez comprendre l'architecture d'un document Google Docs et les éléments qui le composent, ainsi que la relation entre eux. Cette page présente en détail les sujets suivants:
- Modèle conceptuel des éléments du document
- Comment l'API Docs représente ces éléments
- Les propriétés de style des éléments
Éléments de niveau supérieur
L'élément de conteneur le plus externe dans Google Docs est un document. Il s'agit de l'unité qui peut être enregistrée dans Google Drive, partagée avec d'autres utilisateurs et mise à jour avec du texte et des images.
Les éléments de niveau supérieur d'une ressource documents incluent ses Tab, SuggestionsViewMode et autres attributs:
document: {
title: ... ,
revisionId: ... ,
documentId: ... ,
suggestionsViewMode: ... ,
tabs: ...
}
Tabs
Un même document peut contenir plusieurs onglets, qui ont des contenus différents au niveau du texte. La propriété tabs du document est une séquence d'objets Tab. Un Tab se compose des champs suivants:
TabProperties: contient les attributs d'un onglet, tels que l'ID, le titre et l'index.childTabs: affiche les onglets enfants d'un onglet (onglets imbriqués directement sous celui-ci).DocumentTab: représente le contenu textuel d'un onglet.
Les sections suivantes donnent un bref aperçu de la hiérarchie des onglets de document. La représentation JSON des onglets fournit également des informations plus détaillées. Pour en savoir plus sur la fonctionnalité des onglets, consultez Utiliser les onglets.
Pour manipuler les fonctionnalités des onglets de document globaux en dehors du contenu Body, il est presque toujours préférable d'utiliser un ou plusieurs modèles de documents, que vous pouvez utiliser comme base pour générer de nouveaux documents par programmation. Pour en savoir plus, consultez Fusionner du texte dans un document.
Contenu du corps
Body contient généralement le contenu complet de l'onglet d'un document. La plupart des éléments que vous pouvez ou voudriez probablement utiliser de manière programmatique sont des éléments du contenu Body:
Élément structurel
Un StructuralElement décrit un contenu qui fournit une structure au document. Le contenu Body est une séquence d'objets StructuralElement. Un élément de contenu personnalise chaque objet StructuralElement, comme illustré dans le diagramme suivant:
Les éléments structurels et leurs objets de contenu contiennent tous les composants visuels du document. Cela inclut le texte, les images intégrées et la mise en forme.
Structure des paragraphes
Un Paragraph est un StructuralElement représentant un paragraphe. Il contient une plage de contenus terminée par un caractère de nouvelle ligne. Il est composé des objets suivants:
ParagraphElement: décrit le contenu dans un paragraphe.ParagraphStyle: élément facultatif qui définit explicitement les propriétés de style du paragraphe.Bullet: si le paragraphe fait partie d'une liste, élément facultatif qui fournit la spécification des puces.
ParagraphElement fonctionne un peu comme StructuralElement. Un ensemble de types d'éléments de contenu (tels que ColumnBreak et Equation) personnalise son propre ParagraphElement, comme illustré dans le schéma suivant:
Pour obtenir un exemple de structure de document complète, consultez l'exemple de document au format JSON. Dans la sortie, vous pouvez voir de nombreux éléments structurels et de contenu clés, ainsi que l'utilisation des indices de début et de fin, comme décrit dans la section suivante.
Exécutions de texte
Un TextRun est un ParagraphElement qui représente une chaîne de texte contiguë avec le même style de texte. Un paragraphe peut contenir plusieurs exécutions de texte, mais elles ne peuvent jamais franchir les limites de paragraphe. Les contenus sont divisés après un caractère de retour à la ligne pour former des séquences de texte distinctes. Prenons l'exemple d'un petit document comme celui-ci:
Le diagramme suivant montre comment visualiser la séquence de paragraphes du document précédent, chacun avec ses propres paramètres TextRun et Bullet facultatifs.
AutoText
AutoText est un ParagraphElement qui représente un emplacement dans le texte qui est remplacé de manière dynamique par du contenu pouvant changer au fil du temps. Dans Docs, il s'agit des numéros de page.
Indices de début et de fin
Lorsque vous modifiez le contenu de l'onglet d'un document, chaque modification a lieu à un emplacement ou sur une plage du document. Ces emplacements et plages sont spécifiés à l'aide d'index, qui représentent un décalage dans un segment de document contenant. Un segment correspond au corps, à l'en-tête, au pied de page ou à la note de bas de page contenant des éléments structurels ou de contenu. Les indices des éléments d'un segment sont relatifs au début de ce segment.
La plupart des éléments du contenu du corps ont les propriétés startIndex et endIndex basées sur zéro. Ils indiquent le décalage du début et de la fin d'un élément par rapport au début de son segment englobant. Pour savoir comment organiser vos appels d'API Docs par lot, consultez Mises à jour par lot.
Les index sont mesurés en unités de code UTF-16. Cela signifie que les paires de substitution consomment deux index. Par exemple, l'emoji "VISAGE SOURIANT", 😄, est représenté par \uD83D\uDE00 et consomme deux index.
Pour les éléments du corps d'un document, les indices représentent les décalages par rapport au début du contenu du corps, qui est l'élément racine.
Les types de "personnalisation" pour les éléments structurels (SectionBreak, TableOfContents, Table et Paragraph) ne comportent pas ces index, car leur StructuralElement englobant contient ces champs. Cela est également vrai pour les types de personnalisation contenus dans un ParagraphElement, tels que TextRun, AutoText et PageBreak.
Accéder aux éléments
De nombreux éléments peuvent être modifiés à l'aide de la méthode documents.batchUpdate. Par exemple, en utilisant InsertTextRequest, vous pouvez modifier le contenu de tout élément contenant du texte. De même, vous pouvez utiliser UpdateTextStyleRequest pour appliquer une mise en forme à une plage de texte contenue dans un ou plusieurs éléments.
Pour lire des éléments du document, utilisez la méthode documents.get afin d'obtenir un vidage JSON du document complet. Vous pouvez ensuite analyser le fichier JSON obtenu pour trouver les valeurs des éléments individuels. Pour en savoir plus, consultez la section Sortir le contenu du document au format JSON.
L'analyse du contenu peut être utile dans divers cas d'utilisation. Prenons l'exemple d'une application de catalogage de documents listant les documents qu'elle trouve. Cette application peut extraire le titre, l'ID de révision et le numéro de page de début des onglets d'un document, comme illustré dans le diagramme suivant:
Comme il n'existe aucune méthode permettant de lire explicitement ces paramètres, votre application doit obtenir l'intégralité du document, puis analyser le fichier JSON pour extraire ces valeurs.
Héritage de la propriété
Un StructuralElement peut hériter de propriétés de ses objets parents. Les propriétés d'un objet, y compris celles qu'il définit et celles qu'il hérite, déterminent son apparence visuelle finale.
La mise en forme des caractères de texte détermine la façon dont le texte est affiché dans un document (gras, italique et soulignement, par exemple). La mise en forme que vous appliquez remplace la mise en forme par défaut héritée du TextStyle du paragraphe sous-jacent. À l'inverse, tous les caractères dont vous ne définissez pas la mise en forme continuent d'hériter des styles du paragraphe.
La mise en forme du paragraphe détermine la façon dont les blocs de texte sont affichés dans un document, tels que l'alignement, les bordures et les retraits. La mise en forme que vous appliquez remplace la mise en forme par défaut héritée du ParagraphStyle sous-jacent.
À l'inverse, toutes les fonctionnalités de mise en forme que vous ne définissez pas continuent d'hériter du style de paragraphe.