评论是用户对文件提供的反馈,例如,文字处理文档的读者建议如何重述某个句子。注释分为两种类型:锚定注释和未锚定注释。锚定注释与特定位置文档的特定位置相关联,例如文字处理文档中某个句子。反之,未锚定的评论只与文档相关联。
回复附加到评论中,表示用户对评论的回复。借助 Drive API,用户可以对您的应用创建的文档添加评论和回复。评论及其回复统称为讨论。
添加非锚定评论
如需向文档添加非锚定注释,请使用 fileId
参数和包含注释的 comments
资源调用 comments.create
方法。
评论会以纯文本形式插入,但响应正文会提供一个 htmlContent
字段,其中包含经过格式设置以供显示的内容。
添加对评论的回复
如需对评论添加回复,请使用评论、fileId
参数和包含回复的 replies
资源调用 replies.create
方法。
回复会以纯文本形式插入,但响应正文会提供一个 htmlContent
字段,其中包含采用适合显示的格式的内容。
向文档的最新修订版本添加锚定评论
添加评论时,您可能需要将其锚定到文件中的某个区域。锚点用于定义注释引用的文件中的文件修订版本和区域。comments
资源将 anchor
字段定义为 JSON 字符串。
如需添加锚定评论,请执行以下操作:
(可选)调用
revisions.list
方法可列出文档的每个revisionID
。仅当您想将评论锚定到最新修订版本以外的任何修订版本时,才需要执行此步骤。如果要使用最新版本,请为revisionID
使用head
。使用
fileID
参数、包含注释的comments
资源以及包含revisionID
(r
) 和区域 (a
) 的 JSON 锚字符串调用comments.create
方法。
如何定义地区取决于您所处理的文档内容类型。如需了解详情,请参阅定义区域。
指定区域
如前所述,JSON 锚点字符串包含 revisionID
(r
) 和区域 (a
)。区域 (a
) 是一个 JSON 数组,包含用于指定注释锚点格式和位置的区域分类器。分类器可以是图片的二维矩形、文档中的一行文本,或视频中的一段时长。如需定义区域,请选择与您尝试锚定的类型的内容相匹配的区域分类器。例如,如果您的内容是文本,您可能需要使用 txt
或 line
区域分类器。
如需查看 Drive API 中的地区分类器列表,请参阅地区分类器。
以下示例显示了一个 JSON 锚点字符串,用于将注释锚定到文档中两个单独区域中的行:
- 第一个区域从第 12 行 (
'n':12
) 开始,延伸三行 ('l':3
)。 - 第二个区域仅涵盖第 18 行 (
'n':18, 'l':1
`)。
{
'r': 'REVISION_ID',
'a': [
{
'line':
{
'n': 12,
'l': 3,
}
},
{
'line':
{
'n': 18,
'l': 1,
}
}]
}
将 REVISION_ID 替换为 head
或特定修订版本的 ID。
解决评论
在解决了评论后,使用 comment.update
方法将 comments
资源中的 resolved
属性设置为 true
。
当应用将 resolved
属性设置为 true
时,界面应指示注释已得到解决。例如,您的应用可能会:
- 禁止进一步回复,并使所有先前的回复以及原始评论变暗。
- 隐藏已解决的评论。
删除评论
使用 comments.delete
方法删除评论。删除评论后,云端硬盘会将评论资源标记为 "deleted": "true"
。
列出评论
使用 comments.list
方法列出评论。如果您希望在结果中包含已删除的评论,请将 includedDeleted
字段设置为 true
。