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