Gerenciar comentários e respostas

Os comentários são feedbacks fornecidos pelo usuário em um arquivo, como o leitor de um documento de processamento de texto que sugere como reformular uma frase. Existem duas tipos de comentários: ancorados e não ancorados; Um ancorado está associado a um local específico, como uma frase em um documento de processamento de texto, dentro de 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 Drive permite que seus 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 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 que contém 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.

Responda a um comentário

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

A resposta é inserida como texto simples, mas o corpo da resposta fornece uma 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 do arquivo. Um anchor define a revisão e a região do arquivo em um arquivo ao qual um comentário se refere. O recurso comments define 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. Só siga esta etapa se desejar ancorar um comentário em qualquer revisão que não seja a 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 comments que contém o comentário e uma string de âncora JSON contendo o revisionID (r) e região (a).

A forma como você define uma região depende do tipo de conteúdo do documento em que você está trabalhando. com 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 região (a). A região (a) é uma matriz JSON que contém classificadores de região especificando o formato e o local dos comentários. Um classificador pode ser um retângulo bidimensional para uma imagem, uma linha de texto em um documento, ou a duração de um vídeo. Para definir uma região, selecione a região classificador que corresponda ao tipo de conteúdo em que você está tentando fixar. Para Por exemplo, se o conteúdo for texto, é provável que você use txt. ou line.

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

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.

Resolver um comentário

Use o método comment.update para definir a propriedade resolved em comments recurso para true quando um comentário tiver sido endereçado.

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 permitir mais respostas e escurecer todas as respostas anteriores e o original comentário.
  • 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 a recurso de comentário como "deleted": "true".

Listar comentários

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