Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

管理评论

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

本文档介绍了如何使用 Google 表格 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 数组。
包含 CommentAnchor 对象的 sheets.commentAnchors 数组，该数组会将评论锚点 ID 映射到单元格位置（网格范围）。

按范围或工作表过滤评论

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

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

响应示例

以下 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"
}

创建和管理评论

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

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

插入评论

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

以下 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 对象。只有当您是评论串的 headPost CommentThread对象中评论串的作者时，才能删除评论串。
删除回复：如需从 CommentThread中删除特定回复Post，请使用 DeleteCommentReplyRequest 对象。您只能删除自己撰写的回复。您无法删除包含 commentAction 或 assigneeEmail 的回复博文。

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

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

评论更新状态

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

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

CommentUpdateState 中会返回以下状态：

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