Cette page a été traduite par l'API Cloud Translation.

Structure d'un document Google Docs

Pour utiliser efficacement l'API Google Docs, vous devez connaître les l'architecture d'un document Google Docs et les éléments qui composent document, ainsi que la relation entre eux. Cette page fournit une les sections suivantes:

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 le plus externe dans Google Docs est un document. Il s'agit de la qui peut être enregistrée dans Google Drive, partagée avec d'autres utilisateurs et mise à jour avec du texte et des images.

Éléments de premier niveau d'un élément documents la ressource inclut 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 différents au niveau du texte. La propriété tabs du document est une séquence d'objets Tab. Un Tab est composé 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). en dessous).
DocumentTab: Représente le contenu textuel d'un onglet.

</ph> **Figure 1**. Structure des onglets d'un document.

Les sections suivantes donnent un bref aperçu de la hiérarchie des onglets du document. la La représentation JSON des onglets fournit des informations plus détaillées. Consultez Utiliser les onglets. pour en savoir plus sur la fonctionnalité des onglets.

Pour manipuler les fonctionnalités globales de l'onglet du document en dehors du contenu Body, la méthode il est presque toujours préférable d'utiliser un ou plusieurs modèles de documents, que vous pouvez utiliser comme une 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 d'un onglet de document. La plupart des éléments que vous pouvez ou voudriez probablement utiliser de manière programmatique sont des éléments dans le contenu Body:

Élément de structure

Un StructuralElement décrit le contenu qui fournit la structure du document. Le contenu de Body est une séquence d'objets StructuralElement. Un élément de contenu personnalise chaque StructuralElement, comme illustré dans le schéma suivant:

Les éléments structurels et leurs objets de contenu contiennent tous les composants visuels dans le 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. Son contenu est très diversifié se terminant par un caractère de retour à la ligne. Il est composé 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 puce spécifique.

ParagraphElement fonctionne en quelque sorte comme StructuralElement. Un ensemble de types d'éléments de contenu (tels que ColumnBreak et Equation) personnalise ses ParagraphElement, comme illustré dans le schéma suivant:

**Figure 4.** Structure des éléments de paragraphe.

Pour voir un exemple de structure de document complète, consultez le document exemple au format JSON. Dans la sortie, vous pouvez les principaux éléments de structure et de contenu, ainsi que l'utilisation du bouton de démarrage et les index 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. A le paragraphe peut contenir plusieurs séries de texte, mais jamais sur plusieurs paragraphes des limites. Le contenu est divisé après un caractère de retour à la ligne pour former du texte séparé s'exécute. Prenons l'exemple d'un petit document comme celui-ci:

Petit document avec des paragraphes et une liste à puces. — **Figure 5.** Petit document.

Le schéma suivant montre comment visualiser la séquence de paragraphes figurant dans le document précédent, chacune étant associée à une propriété TextRun et une fonction Bullet (facultatives) paramètres.

**Figure 6.** Structure d'une exécution de texte.

AutoText

AutoText est un(e) ParagraphElement représentant une zone dans le texte qui est remplacée dynamiquement dont le contenu peut évoluer 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 d'un document, chaque mise à jour prend ou à une plage spécifique du document. Ces emplacements et sont spécifiées à l'aide d'index, qui représentent un décalage dans une contenant le segment du document. Un segment est le corps, l'en-tête, le pied de page ou note de bas de page contenant des éléments de structure ou de contenu. Les index des éléments dans un segment sont par rapport au début de ce segment.

La plupart des éléments du contenu du corps ont le startIndex basé sur zéro et endIndex. Ceux-ci indiquent le décalage du début d'un élément et se termine par rapport au début du segment englobant. Pour plus d'informations sur l'ordre des appels de l'API Docs par lot, consultez la section API mises à jour.

Les indices sont mesurés en unités de code UTF-16. Cela signifie que les paires de substitution consomment deux index. Par exemple, "GRINNING FACE" d'emoji, ||, est représenté par \uD83D\uDE00 et utilise deux index.

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

La phase de personnalisation pour les données de structure éléments : SectionBreak, TableOfContents Table et Paragraph – ne disposent pas de ces index, car leurs fichiers englobants StructuralElement contient ces champs. Cela s'applique également à la personnalisation types 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 propriété documents.batchUpdate . Par exemple, si vous utilisez 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 les documents.get pour obtenir Vidage JSON du document complet. Vous pouvez ensuite analyser le fichier JSON obtenu dans trouver les valeurs d'éléments individuels. Pour en savoir plus, consultez la page Sortie contenu du document au format JSON.

L'analyse du contenu peut être bénéfique pour divers cas d'utilisation. Réfléchissez à exemple, une application de catalogage de documents répertoriant 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 des , comme illustré dans le schéma suivant:

**Figure 7.** Structure d'un catalogue de documents.

Étant donné qu'il n'existe aucune méthode pour lire ces paramètres explicitement, votre application a besoin pour obtenir l'intégralité du document, puis d'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. Une les propriétés d'un objet, y compris celles qu'il définit et celles dont il hérite, déterminer son apparence visuelle finale.

La mise en forme des caractères détermine la façon dont le texte est affiché dans un document : gras, italique et souligné. La mise en forme que vous appliquez remplace la mise en forme par défaut la mise en forme héritée des paramètres TextStyle À l'inverse, toute les caractères dont vous n'avez pas défini la mise en forme continuent d'hériter les styles de paragraphe.

La mise en forme du paragraphe détermine la façon dont les blocs de texte sont affichés dans un document, telles 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 le style du paragraphe.