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 fournit une présentation détaillée de ces sujets :
- Un modèle conceptuel des éléments du document
- Comment l'API Docs représente ces éléments
- Propriétés de style des éléments
Éléments de premier niveau
L'élément 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 premier niveau d'une ressource documents incluent ses Tab, SuggestionsViewMode et d'autres attributs :
document: {
title: ... ,
revisionId: ... ,
documentId: ... ,
suggestionsViewMode: ... ,
tabs: ...
}
Tabs
Un même document peut contenir plusieurs onglets, qui ont des contenus textuels différents. 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: expose les onglets enfants d'un onglet (onglets directement imbriqués en dessous).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 document, que vous pouvez utiliser comme base pour générer de nouveaux documents de manière programmatique. Pour en savoir plus, consultez Fusionner du texte dans un document.
Contenu du corps
Body contient généralement l'intégralité du contenu d'un onglet de document. La plupart des éléments que vous pouvez ou souhaitez utiliser de manière programmatique sont des éléments du contenu Body :
Élément structurel
Un StructuralElement décrit le contenu qui structure le document. Le contenu Body est une séquence d'objets StructuralElement. Un élément de contenu personnalise chaque objet StructuralElement, comme illustré dans le schéma 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 comporte une plage de contenu qui se termine par un caractère de nouvelle ligne. Il se compose des objets suivants :
ParagraphElement: décrit le contenu d'un paragraphe.ParagraphStyle: élément facultatif qui définit explicitement les propriétés de style du paragraphe.Bullet: élément facultatif qui fournit la spécification de la puce si le paragraphe fait partie d'une liste.
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 complet, consultez l'exemple de document au format JSON. Dans le résultat, vous pouvez voir de nombreux éléments clés de structure et de contenu, ainsi que l'utilisation des index de début et de fin, comme décrit dans une 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 séries de texte, mais celles-ci ne traversent jamais les limites des paragraphes. Le contenu est divisé après un caractère de nouvelle ligne pour former des blocs de texte distincts. Prenons l'exemple d'un petit document comme celui-ci :
Le diagramme suivant montre comment visualiser la séquence de paragraphes dans le 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 un contenu pouvant changer au fil du temps. Dans Docs, il est utilisé pour les numéros de page.
Index de début et de fin
Lorsque vous modifiez le contenu d'un onglet de document, chaque modification a lieu à un emplacement ou dans 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 conteneur. Un segment est le corps, l'en-tête, le pied de page ou la note de bas de page contenant des éléments de structure ou de contenu. Les index des éléments d'un segment sont relatifs au début de ce segment.
La plupart des éléments du corps de contenu possèdent les propriétés startIndex et endIndex (indexées à partir de zéro). Elles 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 en savoir plus sur l'ordre des appels par lot à l'API Docs, 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 index représentent des 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 comporte ces champs. Cela vaut également pour les types de personnalisation contenus dans un ParagraphElement, tels que TextRun, AutoText et PageBreak.
Éléments d'accès
De nombreux éléments sont modifiables avec la méthode documents.batchUpdate. Par exemple, en utilisant InsertTextRequest, vous pouvez modifier le contenu de n'importe quel é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 les éléments du document, utilisez la méthode documents.get pour obtenir un dump JSON du document complet. Vous pouvez ensuite analyser le JSON obtenu pour trouver les valeurs des éléments individuels. Pour en savoir plus, consultez Afficher le contenu du document de sortie au format JSON.
L'analyse du contenu peut être utile dans différents cas d'utilisation. Prenons l'exemple d'une application de catalogage de documents qui liste 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 schéma suivant :
Comme il n'existe aucune méthode pour lire explicitement ces paramètres, votre application doit obtenir l'intégralité du document, puis analyser le code JSON pour extraire ces valeurs.
Héritage de la propriété
Un StructuralElement peut hériter des 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 (par exemple, en gras, en italique ou souligné). La mise en forme que vous appliquez remplace la mise en forme par défaut héritée de la 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 des paragraphes détermine la façon dont les blocs de texte sont affichés dans un document, par exemple l'alignement, les bordures et l'indentation. 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.