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