Structure d'un document Google Docs

Ce guide décrit la structure interne d'un document Google Docs: les éléments qui le composent et leur relation.

Éléments de premier niveau

Les éléments de premier niveau d'un document incluent le corps et plusieurs autres attributs du document dans son ensemble:

document: {
    body: ... ,
    documentStyle: ... ,
    lists: ... ,
    documentId: ... ,
    namedStyles: ... ,
    revisionId: ... ,
    title: ...
}

Tout au long de ce guide, nous vous présentons une vue minimaliste des éléments structuraux du document. Par souci de simplicité et de clarté. Pour obtenir une représentation complète de la structure du document, envisagez d'utiliser l'utilitaire décrit dans la section Générer le contenu du document au format JSON.

Pour manipuler les fonctionnalités globales du document en dehors du contenu du corps, 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.

Corps du texte

La plupart des éléments que vous pouvez ou souhaitez probablement utiliser de manière programmatique sont des éléments inclus dans le corps du texte:

Éléments structurels

Le contenu du corps n'est qu'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 l'ensemble du texte du document, les images intégrées, etc.

Les types En-tête, Pied de page et Note de bas de page comportent des éléments de contenu qui contiennent également une séquence d'éléments structurels.

Les paragraphes contiennent un type d'élément spécial appelé ParagraphElement, qui fonctionne comme un StructuralElement. Un ensemble de types d'éléments de contenu personnalise son propre ParagraphElement, comme illustré dans le schéma suivant:

Pour obtenir un exemple de structure complète de document, consultez l'exemple de vidage d'un document au format JSON. La sortie affiche de nombreux éléments clés de la structure et du contenu, ainsi que l'utilisation des index de début et de fin, comme décrit dans la section suivante.

Index de début et de fin

La plupart des éléments du contenu du corps ont les propriétés startIndex et endIndex. Ils indiquent le décalage entre le début et la fin d'un élément par rapport au début du segment parent.

Un segment correspond au corps, à l'en-tête, au pied de page ou à la note de bas de page qui contient des éléments de structure ou de contenu. Les index des éléments d'un segment sont relatifs au début de ce segment.

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 VISIBLE" permet d'être représenté sous la forme "\uD83D\uDE00" et de consommer deux index.

Pour les éléments d'un corps de document, les index représentent les décalages par rapport au début du contenu du corps, qui est l'élément "racine".

Les éléments non inclus dans le contenu ne possèdent pas ces propriétés d'index. Ils sont de portée mondiale et n'incluent pas le concept de position.

Les types "personnalisés" des éléments structurels (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.

Structure de paragraphe

Un paragraphe se compose des éléments suivants:

• elements : séquence contenant une ou plusieurs instances de textRun.
• paragraphStyle : élément facultatif qui définit explicitement les propriétés de style pour le paragraphe.
• bullet : élément facultatif qui fournit la spécification de puce si le paragraphe fait partie d'une liste.

Exécutions de texte

Un textRun 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 peuvent pas dépasser les limites du paragraphe. Prenons l'exemple d'un petit document comme celui-ci:

Le schéma suivant montre comment visualiser la séquence de paragraphes dans le document ci-dessus, chacun avec ses propres exécutions de texte et des paramètres de puces facultatifs.

Accéder aux éléments

De nombreux éléments peuvent être modifiés à l'aide de la méthode BatchUpdate. Par exemple, à l'aide du type de requête 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 get afin d'obtenir un fichier de vidage JSON du document complet. (Pour savoir comment procéder, consultez l'exemple Contenu du document de sortie au format JSON.) Vous pouvez ensuite analyser le fichier JSON ainsi obtenu pour trouver les valeurs de chaque élément.

L'analyse du contenu peut être utile dans divers cas d'utilisation. Prenons l'exemple d'une application de catalogue de documents qui répertorie les documents qu'elle trouve. Cette application peut extraire le titre, l'ID de révision et le numéro de page de démarrage d'un document, comme indiqué dans le schéma suivant:

Comme il n'existe aucune méthode permettant de lire ces paramètres explicitement, votre application doit obtenir l'intégralité du document, puis analyser le fichier JSON pour extraire ces valeurs.