Les commentaires sont des commentaires fournis par les utilisateurs sur un fichier, par exemple document de traitement de texte suggérant comment reformuler une phrase. Il y a deux types de commentaires: commentaires ancrés et commentaires non ancrés. Une vue ancrée le commentaire est associé à un lieu spécifique, comme une phrase dans une document de traitement de texte, dans une version spécifique d'un document. À l'inverse, un commentaire non ancré est simplement associé au document.
Les réponses sont jointes aux commentaires et représentent la réponse d'un utilisateur au commentaire. L'API Drive permet à vos utilisateurs d'ajouter des commentaires et des réponses les documents créés par votre application. Collectivement, un commentaire contenant des réponses est appelé une discussion.
Ajouter un commentaire non ancré
Pour ajouter un commentaire non ancré à un document, appelez la méthode comments.create
avec le paramètre fileId
et une
Ressource comments
contenant le commentaire.
Le commentaire est inséré en texte brut, mais le corps de la réponse fournit une
Champ htmlContent
avec du contenu mis en forme pour être affiché.
Ajouter une réponse à un commentaire
Pour répondre à un commentaire, appelez la méthode
replies.create
avec le commentaire.
le paramètre fileId
et une ressource replies
;
contenant la réponse.
La réponse est insérée en texte brut, mais le corps de la réponse fournit une
Champ htmlContent
avec du contenu mis en forme pour être affiché.
Ajouter un commentaire ancré à la dernière révision d'un document
Lorsque vous ajoutez un commentaire, vous pouvez l'ancrer à une zone du fichier. Une
ancre définit la révision et la région du fichier dans un fichier auquel un commentaire
renvoie. La ressource comments
définit
anchor
sous forme de chaîne JSON.
Pour ajouter un commentaire ancré:
(Facultatif) Appelez la méthode
revisions.list
. pour répertorier toutes les valeursrevisionID
d'un document. Ne suivez cette étape que si vous souhaitez ancrer un commentaire à toute révision autre que la dernière révision. Si vous souhaitez utiliser la dernière révision, utilisezhead
pourrevisionID
.Appelez la méthode
comments.create
. avec le paramètrefileID
, un élémentcomments
ressource contenant le commentaire, ainsi qu'une chaîne d'ancrage JSON contenant le paramètrerevisionID
(r
) et la région (a
).
La manière dont vous définissez une région dépend du type de contenu du document sur lequel vous travaillez . Pour en savoir plus, consultez Définir une région.
Définir une région
Comme indiqué précédemment, la chaîne d'ancrage JSON contient un élément revisionID
(r
) et
(a
). La région (a
) est un tableau JSON contenant des classificateurs de région
spécifiant le format et l'emplacement d'ancrage d'un commentaire. Un classificateur
peut être un rectangle en deux dimensions pour une image, une ligne de texte dans un document,
ou la durée d'une vidéo. Pour définir une région, sélectionnez la région
classificateur correspondant au type de contenu auquel vous essayez de vous ancrer. Pour
Par exemple, si votre contenu est du texte, vous utiliserez probablement la méthode txt
ou le classificateur par région line
.
Pour obtenir la liste des classificateurs par région dans l'API Drive, consultez Région classificateurs.
L'exemple suivant montre une chaîne d'ancrage JSON qui ancre les commentaires aux lignes dans deux zones distinctes d'un document:
- La première zone commence à la ligne 12 (
'n':12
) et s'étend sur trois lignes ('l':3
). - La deuxième zone ne couvre que la ligne 18 (
'n':18, 'l':1
).
{
'r': 'REVISION_ID',
'a': [
{
'line':
{
'n': 12,
'l': 3,
}
},
{
'line':
{
'n': 18,
'l': 1,
}
}]
}
Remplacez REVISION_ID par head
ou l'ID d'une
la révision.
Fermer un commentaire
Utilisez la méthode comment.update
pour définir
la propriété resolved
dans comments
;
vers true
lorsqu'un commentaire a été traité.
Lorsque votre application définit la propriété resolved
sur true
, votre UI doit indiquer
que le commentaire a été traité. Par exemple, votre application peut:
- Interdire les autres réponses et estomper toutes les réponses précédentes, ainsi que l'originale commentaire.
- Masquer les commentaires fermés.
Supprimer un commentaire
Utilisez la méthode comments.delete
pour
supprimer des commentaires. Lorsqu'un commentaire est supprimé, Drive le marque
la ressource de commentaire en tant que "deleted": "true"
.
Lister les commentaires
Utilisez la méthode comments.list
pour répertorier
commentaires. Si vous souhaitez inclure les commentaires supprimés dans les résultats, définissez le paramètre
le champ includedDeleted
sur true
.