Gerenciar comentários e respostas

Comentários são feedbacks fornecidos pelo usuário sobre um arquivo, como um leitor de documentos de processamento de texto que sugerem a reformulação de uma frase. Há dois tipos de comentário: comentários ancorados e não ancorados. Um comentário ancorado é associado a um local específico, como uma frase em um documento de processamento de texto, em uma versão específica de um documento. Por outro lado, um comentário não ancorado é apenas associado ao documento.

As respostas são anexadas aos comentários e representam a resposta de um usuário ao comentário. A API Google Drive permite que os usuários adicionem comentários e respostas a documentos criados pelo app. Coletivamente, um comentário com respostas é conhecido como discussão.

Adicionar um comentário não ancorado

Para adicionar um comentário não ancorado a um documento, chame o método comments.create com o parâmetro fileId e um recurso comments contendo o comentário.

O comentário é inserido como texto simples, mas o corpo da resposta fornece um campo htmlContent com conteúdo formatado para exibição.

Adicionar resposta a um comentário

Para adicionar uma resposta a um comentário, chame o método replies.create com o comentário, o parâmetro fileId e um recurso reply que contém a resposta.

A resposta é inserida como texto simples, mas o corpo da resposta fornece um campo htmlContent com conteúdo formatado para exibição.

Adicionar um comentário ancorado à revisão mais recente de um documento

Ao adicionar um comentário, você pode ancorá-lo a uma região no arquivo. Uma âncora define a revisão e a região do arquivo em um arquivo a que um comentário se refere. O recurso comments define o campo anchor como uma string JSON.

Para adicionar um comentário ancorado, siga estas etapas:

  1. (Opcional) Chame o método revisions.list para listar cada revisionID de um documento. Siga esta etapa apenas se você quiser ancorar um comentário em qualquer revisão diferente da mais recente. Se você quiser usar a revisão mais recente, use head para o revisionID.

  2. Chame o método comments.create com o parâmetro fileID, um recurso comments que contém o comentário e uma string âncora JSON contendo o revisionID (r) e a região (a).

A maneira como você define uma região depende do tipo de conteúdo do documento com o qual você está trabalhando. Para mais informações, consulte Definir uma região abaixo.

Definir uma região

Como mencionado anteriormente, a string de âncora JSON contém um revisionID (r) e uma região (a). A região (a) é uma matriz JSON com classificadores de região que especificam o formato e o local a que um comentário está ancorado. Um classificador pode ser um retângulo bidimensional de uma imagem, uma linha de texto em um documento, uma duração em um vídeo e assim por diante. Para definir uma região, selecione o classificador de região que corresponde ao tipo de conteúdo em que você está tentando fixar. Por exemplo, se o seu conteúdo for texto, você provavelmente usará o classificador de região txt ou line.

Para conferir uma lista de classificadores de região na API Drive, consulte Classificadores de região.

O exemplo a seguir mostra uma string de âncora JSON que ancora comentários a linhas em duas áreas separadas de um documento:

  • A primeira área começa na linha 12 ('n':12) e se estende por três linhas ('l':3).
  • A segunda área cobre apenas a linha 18 ('n':18, 'l':1`).
    {
      'r': 'REVISION_ID',
      'a': [
      {
        'line':
        {
          'n': 12,
          'l': 3,
        }
      },
      {
        'line':
        {
          'n': 18,
          'l': 1,
        }
      }]
    }

Substitua REVISION_ID por head ou pelo ID de uma revisão específica.

Resolver um comentário

Use o método comment.update para definir a propriedade resolved no recurso comments como true quando um comentário for abordado.

Quando o app define a propriedade resolved como true, a interface precisa indicar que o comentário foi resolvido. Por exemplo, seu app pode:

  • Não permite mais respostas e escurece todas as respostas anteriores, além do comentário original.
  • Ocultar comentários resolvidos.

Excluir um comentário

Use o método comments.delete para excluir comentários. Quando um comentário é excluído, o Drive marca o recurso de comentário como "deleted": "true".

Comentários da lista

Use o método comments.list para listar os comentários. Se você quiser incluir comentários excluídos nos resultados, defina o campo includedDeleted como true.