管理评论

Google 表格允许用户通过在特定单元格中添加评论来进行协作。

本文档介绍了如何使用 Google Sheets API 以编程方式读取、创建、回复、更新或删除评论。

阅读评论

当您对 spreadsheets 资源使用 get 方法来检索电子表格时，默认情况下会省略评论线程和锚点。

如需在响应中包含注释，请将 commentsViewMode 查询参数设置为 COMMENTS_VIEW_MODE_INCLUDED。 此外，如果调用用户对相应文件具有评论访问权限，则将查询参数设置为 COMMENTS_VIEW_MODE_DEFAULT_FOR_CURRENT_ACCESS 也会返回评论。

响应中会同时返回 comments 和 sheets.commentAnchors 字段。

以下代码示例展示了如何使用 get 请求从电子表格中检索评论线程及其锚点（网格范围）：

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?commentsViewMode=COMMENTS_VIEW_MODE_INCLUDED&fields=spreadsheetId,comments,sheets(properties(sheetId,title),commentAnchors)

在响应中，评论会返回到以下两个位置：

  • 包含 CommentThread 对象的全局 comments 数组。
  • sheets.commentAnchors 数组，包含将注释锚点 ID 映射到单元格位置（网格范围）的 CommentAnchor 对象。

按范围或工作表过滤评论

检索电子表格时，您可以通过以下方式过滤返回的数据：指定范围（在 spreadsheets.get 方法中使用 ranges 查询参数）或工作表（在 spreadsheets.getByDataFilter 方法的请求正文中使用 dataFilters 字段）。

  • 如果您按范围或工作表进行过滤：系统只会返回锚定在指定范围或工作表内的评论串。不包括未锚定的评论（例如原始单元格坐标已被删除的评论）。
  • 如果您不按范围或工作表进行过滤：系统会返回所有评论串，包括未锚定的评论。

响应示例

以下 JSON 响应示例展示了锚定到 ID 为 0 的工作表中单元格 A1（第 0 行，第 0 列）的评论串：

{
  "spreadsheetId": "SPREADSHEET_ID",
  "sheets": [
    {
      "properties": {
        "sheetId": 0,
        "title": "Sheet1"
      },
      "commentAnchors": [
        {
          "anchorId": "ANCHOR_ID",
          "range": {
            "sheetId": 0,
            "startRowIndex": 0,
            "endRowIndex": 1,
            "startColumnIndex": 0,
            "endColumnIndex": 1
          }
        }
      ]
    }
  ],
  "comments": [
    {
      "commentId": "COMMENT_ID",
      "anchorId": "ANCHOR_ID",
      "headPost": {
        "postId": "POST_ID",
        "content": "This is a comment thread head post.",
        "contentHtml": "The content of the post as HTML.",
        "author": {
          "displayName": "DISPLAY_NAME",
          "me": true,
          "user": "users/USER"
        },
        "createTime": "2026-07-01T10:13:12Z",
        "updateTime": "2026-07-01T10:13:12Z"
      },
      "replies": [
        {
          "postId": "REPLY_POST_ID",
          "content": "This is a reply to the comment.",
          "author": {
            "displayName": "DISPLAY_NAME",
            "me": false
          },
          "createTime": "2026-07-01T10:15:00Z",
          "updateTime": "2026-07-01T10:15:00Z"
        }
      ],
      "status": "OPEN"
    }
  ],
  "commentsViewMode": "COMMENTS_VIEW_MODE_INCLUDED"
}

创建和管理注释

您可以使用 spreadsheets 资源中的 batchUpdate 方法以编程方式添加、修改和删除评论或回复。

执行涉及评论的批量更新时，您应监控潜在的部分失败情况。如需了解详情，请参阅评论更新状态。

插入评论

如需在电子表格中插入评论串，请使用 InsertCommentRequest 对象。您必须使用 GridCoordinate 对象提供评论文本内容和评论锚定的 coordinate。

以下 JSON 示例展示了如何向 ID 为 0 的工作表中单元格 B2（第 1 行，第 1 列）添加未分配的评论线程：

{
  "requests": [
    {
      "insertComment": {
        "content": "This is a comment added using the API.",
        "coordinate": {
          "sheetId": 0,
          "rowIndex": 1,
          "columnIndex": 1
        }
      }
    }
  ]
}

您可以在 assigneeEmailAddress 字段中提供特定用户的电子邮件地址，将评论分配给该用户：

{
  "requests": [
    {
      "insertComment": {
        "content": "Please review the data in this cell.",
        "assigneeEmailAddress": "ASSIGNEE_EMAIL_ADDRESS",
        "coordinate": {
          "sheetId": 0,
          "rowIndex": 1,
          "columnIndex": 1
        }
      }
    }
  ]
}

添加回复或采取行动

如需回复评论串、解决或重新打开评论串，请使用 AddCommentReplyRequest 对象。

您必须提供 commentId 和 post，其中回复由 Post 对象表示。

Post 对象包含回复 content，并且可以选择性地指定 commentAction（包括将评论串标记为 RESOLVE 或 REOPEN 的操作）。它由 CommentActionType 对象表示。

您还可以在 Post 对象中指定新的 assigneeEmail 来重新分配评论串。

以下 JSON 示例展示了如何回复现有评论串：

{
  "requests": [
    {
      "addCommentReply": {
        "commentId": "COMMENT_ID",
        "post": {
          "content": "Replying to the comment thread."
        }
      }
    }
  ]
}

以下 JSON 示例展示了如何解决评论串（不需要 content 字段）：

{
  "requests": [
    {
      "addCommentReply": {
        "commentId": "COMMENT_ID",
        "post": {
          "commentAction": "RESOLVE"
        }
      }
    }
  ]
}

以下 JSON 示例展示了如何重新分配评论串：

{
  "requests": [
    {
      "addCommentReply": {
        "commentId": "COMMENT_ID",
        "post": {
          "content": "Replying to the comment thread.",
          "assigneeEmail": "ASSIGNEE_EMAIL"
        }
      }
    }
  ]
}

修改帖子

如需修改您撰写的帖子的文字内容，请使用 UpdateCommentPostRequest 对象。您必须指定相应线程的 commentId、要修改的帖子的 postId 以及新的纯文本 content。

以下 JSON 示例展示了如何修改帖子：

{
  "requests": [
    {
      "updateCommentPost": {
        "commentId": "COMMENT_ID",
        "postId": "POST_ID",
        "content": "This is the updated comment text."
      }
    }
  ]
}

删除评论和回复

如要删除评论和回复，您可以通过以下两种方法操作：

  • 删除评论串：如需移除整个CommentThread，请使用 DeleteCommentRequest 对象。只有当您是 CommentThread 对象中 headPost 的作者时，才能删除评论串。

  • 删除回复：如需从 CommentThread 中删除特定回复 Post，请使用 DeleteCommentReplyRequest 对象。您只能删除自己撰写的回复。您无法删除包含 commentAction 或 assigneeEmail 的回复帖子。

以下 JSON 示例展示了如何删除评论串：

{
  "requests": [
    {
      "deleteComment": {
        "commentId": "COMMENT_ID"
      }
    }
  ]
}

评论更新状态

需要保存评论串（例如插入评论或添加回复）的请求可能会出现部分失败。在这些情况下，电子表格模型更改（例如更新单元格值或添加工作表）可能会成功提交，但关联的注释可能无法保存。

您可以通过检查 spreadsheets.batchUpdate 方法的响应正文中的 commentUpdateState 字段来验证评论更新是否已成功应用。该字段由 CommentUpdateState 对象表示。

CommentUpdateState 中会返回以下状态：

  • NO_UPDATES_REQUESTED：批处理操作中未请求任何评论更新。
  • ALL_SAVED：所有请求的评论更新均已成功应用。
  • ALL_FAILED_UNKNOWN_REASON：所有请求的评论更新均未能保存，即使其他电子表格更改可能已提交。