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 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.
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:
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.](https://developers-dot-devsite-v2-prod.appspot.com/static/docs/api/images/simpledoc.png?authuser=2&hl=fr)
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.
AutoText
AutoText
est un
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 au sein d'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 en savoir plus,
sur l'ordre des appels de l'API Docs par lot, consultez la section API
mises à jour.
Les index 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
La page 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 contenu 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
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:
É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.