管理评论和回复

评论是用户针对文件提供的反馈,例如建议如何改写句子的字处理文档的读者。注释有两种类型:锚定注释和未锚定注释。锚定评论与特定位置(例如文字处理文档中的句子)的特定版本相关联。相反,未锚定的评论仅与文档相关联。

回复会附加到评论中,表示用户对评论的回复。借助 Google Drive API,用户可以向应用创建的文档添加评论和回复。带回复的评论统称为“讨论”

添加未锚定评论

如需向文档添加未锚定评论,请使用 fileId 参数和包含该评论的 comments 资源调用 comments.create 方法。

注释以纯文本形式插入,但响应正文会提供一个 htmlContent 字段,其中包含已格式化为显示的内容。

对评论添加回复

如需为评论添加回复,请调用 replies.create 方法,并传入评论、fileId 参数和包含回复的 reply 资源。

回复以纯文本形式插入,但响应正文会提供一个 htmlContent 字段,其中包含已格式化为显示的内容。

向文档的最新修订版本添加锚定评论

添加评论时,您可能想要将其锚定到文件中的某个区域。锚标记定义评论引用的文件中的文件修订版本和区域。comments 资源将 anchor 字段定义为 JSON 字符串。

如需添加锚定评论,请执行以下操作:

  1. (可选)。调用 revisions.list 方法可列出文档的每个 revisionID。仅当要将评论锚定到最新修订版本以外的任何修订版本时,才需要执行此步骤。如果要使用最新修订版本,请为 revisionID 使用 head

  2. 调用 comments.create 方法,其中包含 fileID 参数、一个包含注释的 comments 资源,以及一个包含 revisionID (r) 和区域 (a) 的 JSON 锚字符串。

区域的定义方式取决于您所使用的文档内容的类型。如需了解详情,请参阅下文的定义区域

定义区域

如前所述,JSON 定位字符串包含 revisionID (r) 和区域 (a)。区域 (a) 是一个 JSON 数组,其中包含区域分类器,用于指定评论锚定的格式和位置。分类器可以是表示图片的二维矩形、文档中的行文本、视频中的时长等等。如需定义区域,请选择与您尝试锚定的内容类型匹配的区域分类。例如,如果您的内容是文本,您可能需要使用 txtline 区域分类器。

如需查看 Drive API 中的区域分类器列表,请参阅区域分类器

以下示例展示了一个 JSON 锚字符串,该字符串可将注释锚定到文档的 2 个不同区域中的行:

  • 第一个区域从第 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