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 ces documents. Cette page fournit une présentation détaillée de ces sujets:
- 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 premier niveau
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 Body, Header, Footer et plusieurs autres attributs:
document: {
body: ... ,
documentStyle: ... ,
lists: ... ,
documentId: ... ,
namedStyles: ... ,
revisionId: ... ,
title: ...
}
Pour manipuler les fonctionnalités de document globales 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 l'intégralité du contenu du 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 de structure
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 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 de paragraphe
Un Paragraph est un StructuralElement représentant un paragraphe. Il comporte une plage de contenu qui se
termine par un caractère de retour à la 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 pour le paragraphe.Bullet: si le paragraphe fait partie d'une liste, élément facultatif qui fournit la spécification des puces.
ParagraphElement fonctionne en quelque sorte 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 cet exemple de document au format JSON. Dans le résultat, vous pouvez voir de nombreux éléments de structure et de contenu clés, ainsi que l'utilisation des index 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 le texte ne dépasse jamais les limites de paragraphe. Le contenu est divisé après un caractère de retour à la ligne pour former des exécutions de texte distinctes. Prenons l'exemple d'un petit document comme celui-ci:
Le schéma 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 espace dans un texte qui est remplacé de manière dynamique par du contenu susceptible de 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 document, chaque mise à jour 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 conteneur. Un segment correspond au corps, à l'en-tête, au pied de page ou à la note de bas de page contenant des éléments de structure ou de contenu. Les indices des éléments d'un segment sont exprimés par rapport 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 en savoir plus sur l'ordre des appels d'API Docs par lot, consultez la section Mises à jour par lot.
Les indices sont mesurés en unités de code UTF-16. Cela signifie que les paires de substitution consomment deux index. Par exemple, l'emoji "GRINNING FACE" (FAIBLE DE GRINAGE) , , est représenté par \uD83D\uDE00 et utilise deux index.
Pour les éléments inclus dans le corps d'un document, les index représentent les décalages à partir du début du contenu du corps, qui est l'élément "racine".
Les types de "personnalisation" des éléments structurels (SectionBreak, TableOfContents, Table et Paragraph) ne disposent pas de ces index, car leur StructuralElement englobant contient ces champs. Cela s'applique également aux types de personnalisation contenus dans un ParagraphElement, tels que TextRun, AutoText et PageBreak.
Accéder aux éléments
La méthode documents.batchUpdate permet de modifier de nombreux éléments. 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 d'éléments individuels. Pour en savoir plus, consultez Générer le contenu du document au format JSON.
L'analyse du contenu peut être bénéfique pour 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épart d'un document, comme illustré dans le schéma 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 des propriétés de ses objets parents. Les propriétés d'un objet, y compris celles qu'il définit et celles dont 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 de la propriété 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.