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 palavras que sugerem como reformular 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 é 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 aos 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 replies contendo 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 querer 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:

  1. (Opcional) Chame o método revisions.list para listar cada revisionID de um documento. Siga esta etapa apenas se você quiser fixar um comentário em qualquer revisão diferente da mais recente. Se você quiser usar a revisão mais recente, use head para 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 contendo 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 que especificam 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 que corresponde ao tipo de conteúdo em que você está tentando fixar. Por exemplo, se o conteúdo for de 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 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 abordado.

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

  • Não permitir mais respostas e escurecer 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. Para incluir comentários excluídos nos resultados, defina o campo includedDeleted como true.