Pour utiliser l'API Google Docs de manière efficace, vous devez comprendre l'architecture d'un document Google Docs, les éléments qui le composent, ainsi que la relation entre eux. Cette page offre un aperçu détaillé de ces sujets:
- 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 de conteneur de plus haut niveau dans Google Docs est un document. Ce bloc peut être enregistré dans Google Drive, partagé avec d'autres utilisateurs, et mis à jour avec du texte et des images.
Les éléments de premier niveau d'une ressource documents incluent Body, Header, Footer et plusieurs autres attributs:
document: {
body: ... ,
documentStyle: ... ,
lists: ... ,
documentId: ... ,
namedStyles: ... ,
revisionId: ... ,
title: ...
}
Pour manipuler des 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 document, 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 souhaitez probablement utiliser de manière programmatique sont des éléments du contenu Body:
Élément structurel
Une StructuralElement décrit le contenu qui fournit la structure du 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 constitué 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 pour le paragraphe.Bullet: si le paragraphe fait partie d'une liste, un élément facultatif qui fournit la spécification de puce.
Le ParagraphElement fonctionne comme un StructuralElement. Un ensemble de types d'éléments de contenu (tels que ColumnBreak et Equation) personnalise sa propre propriété 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. La sortie affiche un grand nombre des principaux éléments de structure et de contenu, 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 celles-ci ne dépassent jamais les limites du 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 une partie du texte qui est remplacée dynamiquement 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 document, chaque mise à jour est effectuée à un emplacement ou à l'échelle du document. Ces emplacements et ces plages sont spécifiés à l'aide d'index, qui représentent un décalage au sein d'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 qui contient des éléments structurels 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 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 du segment qui le contient. Pour en savoir plus sur l'ordonnancement des appels d'API Docs par lot, consultez la section 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 GRAND INDICATEUR, GOAL, est représenté par \uD83D\uDE00 et utilise deux index.
Pour les éléments d'un corps de document, les index représentent les décalages depuis le début du contenu du corps, qui est l'élément "racine".
Les types "personnalisés" des éléments de structure (SectionBreak, TableOfContents, Table et Paragraph) ne disposent pas de ces index, car leur conteneur StructuralElement contient ces champs. Cela s'applique également aux types de personnalisation contenus dans un ParagraphElement, tels que TextRun, AutoText et PageBreak.
Éléments d'accès
De nombreux éléments peuvent être modifiés avec la méthode documents.batchUpdate. Par exemple, à l'aide de 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 les é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 Contenu du document de sortie 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 répertoriant les documents trouvés. 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 ces paramètres explicitement, votre application doit récupérer 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 le rendu du texte 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 fichier TextStyle du paragraphe sous-jacent. À l'inverse, 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 de paragraphe détermine la façon dont les blocs de texte sont affichés dans un document, comme 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, les fonctionnalités de mise en forme que vous ne définissez pas continuent d'hériter du style de paragraphe.