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:
(Opcional) Chame o método
revisions.list
para listar cadarevisionID
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, usehead
pararevisionID
.Chame o método
comments.create
com o parâmetrofileID
, um recursocomments
que contém o comentário e uma string de âncora JSON contendorevisionID
(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
.