评论是用户针对文件提供的反馈,例如文字处理文档读者,建议如何改写句子。注释分为两种类型:锚定注释和未锚定注释。锚定评论与特定版本文档的特定位置(例如文字处理文档中的句子)相关联。相反,未锚定的评论仅与文档相关联。
回复附加到评论中,表示用户对评论的响应。借助 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
。