Gérer les commentaires et les réponses

Les commentaires sont des commentaires envoyés 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é:

  1. (Facultatif) Appelez la méthode revisions.list. pour répertorier toutes les valeurs revisionID 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, utilisez head pour revisionID.

  2. Appelez la méthode comments.create. avec le paramètre fileID, un élément comments ressource contenant le commentaire, ainsi qu'une chaîne d'ancrage JSON contenant le paramètre revisionID (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.