Gerenciar comentários e respostas

Os comentários são feedbacks fornecidos pelo usuário sobre um arquivo, como um leitor de um documento de processamento de texto sugerindo como reformular uma frase. Há dois tipos de comentários: com âncora e sem âncora. Um comentário fixado é 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 sem âncora é 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 Drive permite que os usuários adicionem comentários e respostas a documentos criados pelo seu app. Coletivamente, um comentário com respostas é conhecido como uma discussão.

Adicionar um comentário sem âncora

Para adicionar um comentário sem âncora a um documento, chame o método comments.create com o parâmetro fileId e um recurso comments que contenha 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 uma 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 replies que contenha 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 fixado à revisão mais recente de um documento

Ao adicionar um comentário, talvez você queira anexá-lo a uma região no arquivo. Uma âncora define a revisão e a região de 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 fixado:

  1. (Opcional). Chame o método revisions.list para listar todos os revisionID de um documento. Siga esta etapa apenas se você quiser ancorar um comentário em qualquer revisão, exceto a 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 de âncora JSON que contém o revisionID (r) e a região (a).

A forma de definir uma região depende do tipo de conteúdo do documento com que você está trabalhando. Para mais informações, consulte Definir uma região.

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 que contém classificadores de região especificando o formato e o local em que um comentário está ancorado. Um classificador pode ser um retângulo bidimensional para uma imagem, uma linha de texto em um documento ou uma duração em um vídeo. Para definir uma região, selecione o classificador de região correspondente ao tipo de conteúdo que você quer ancorar. Por exemplo, se o conteúdo for texto, provavelmente você 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 em 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 enviado.

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

  • Não permite mais respostas e desativa 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 do comentário como "deleted": "true".

Listar comentários

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