Google 幻灯片允许用户通过在幻灯片和页面元素上添加评论来协作处理内容。
本文档介绍了如何使用 Google Slides API 以编程方式读取、创建、回复、更新或删除评论。
阅读评论
当您对 presentations 资源使用 get 方法来检索演示时，系统默认会省略评论线程和锚点。
如需在响应中包含注释，请将 commentsViewMode 查询参数设置为 COMMENTS_VIEW_MODE_INCLUDED。
此外，如果调用用户对相应文件具有评论访问权限，则将查询参数设置为 COMMENTS_VIEW_MODE_DEFAULT_FOR_CURRENT_ACCESS 也会返回评论。
响应中会同时返回 comments 和 commentAnchors 字段。
以下代码示例展示了如何使用 get 请求从演示中检索评论线程及其锚点：
GET https://slides.googleapis.com/v1/presentations/PRESENTATION_ID?commentsViewMode=COMMENTS_VIEW_MODE_INCLUDED&fields=presentationId,comments,slides(objectId,commentAnchors)
在响应中，评论会返回到以下两个位置：
- 包含
CommentThread对象的全局comments数组。 commentAnchors数组，包含将注释锚点 ID 映射到网页或页面元素位置（对象锚点）的CommentAnchor对象。
阅读特定网页上的评论
您还可以使用 presentations.pages 资源上的 pages.get 方法检索特定网页的注释和锚点。设置 commentsViewMode 查询参数以纳入特定网页目标的注释：
GET https://slides.googleapis.com/v1/presentations/PRESENTATION_ID/pages/PAGE_ID?commentsViewMode=COMMENTS_VIEW_MODE_INCLUDED&fields=objectId,comments,commentAnchors
响应示例
以下 JSON 示例响应显示了锚定到幻灯片页面上某个形状内的文本范围的评论线程：
{
"presentationId": "PRESENTATION_ID",
"slides": [
{
"objectId": "SLIDE_PAGE_ID",
"commentAnchors": [
{
"anchorId": "ANCHOR_ID",
"objectAnchors": [
{
"objectId": "SHAPE_OBJECT_ID",
"shapeTextAnchors": {
"ranges": [
{
"startIndex": 0,
"endIndex": 12
}
]
}
}
]
}
]
}
],
"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"
}
创建和管理注释
您可以使用 presentations 资源上的 batchUpdate 方法以编程方式添加、修改和删除评论或回复。
执行涉及评论的批量更新时，您应监控潜在的部分失败情况。如需了解详情，请参阅评论更新状态。
插入评论
如需在演示文稿中插入评论串，请使用 InsertCommentRequest 对象。您必须提供评论文本内容和定位位置。锚点位置必须指定以下其中一项：
objectId：要将注释锚定到的幻灯片页面或页面元素（例如形状或表格）的对象 ID。shapeTextAnchor：将注释锚定到形状中的一段文本。tableCellTextAnchor：将注释锚定到表格单元格中的一段文本。tableAnchor： 将注释锚定到表格中的某个单元格范围。
以下 JSON 示例展示了如何添加锚定到幻灯片页面的评论串：
{
"requests": [
{
"insertComment": {
"content": "This is a comment added using the API.",
"objectId": "SLIDE_PAGE_ID"
}
}
]
}
您可以在 assigneeEmailAddress 字段中提供特定用户的电子邮件地址，将评论分配给该用户：
{
"requests": [
{
"insertComment": {
"content": "Please review this slide.",
"assigneeEmailAddress": "ASSIGNEE_EMAIL_ADDRESS",
"objectId": "SLIDE_PAGE_ID"
}
}
]
}
添加回复或采取行动
如需回复评论串、解决或重新打开评论串，请使用 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 示例展示了如何解决评论串：
{
"requests": [
{
"addCommentReply": {
"commentId": "COMMENT_ID",
"post": {
"commentAction": "RESOLVE"
}
}
}
]
}
修改帖子
如需修改您撰写的帖子的文字内容，请使用 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"
}
}
]
}
评论更新状态
需要保存评论串（例如插入评论或添加回复）的请求可能会出现部分失败。在这些情况下，演示模型更改（例如更新幻灯片内容或背景）可能已成功提交，但相关联的注释可能无法保存。
您可以通过检查 presentations.batchUpdate 方法的响应正文中的 commentUpdateState 字段来验证评论更新是否已成功应用。该字段由 CommentUpdateState 对象表示。
CommentUpdateState 中会返回以下状态：
NO_UPDATES_REQUESTED：批处理操作中未请求任何评论更新。ALL_SAVED：所有请求的评论更新均已成功应用。ALL_FAILED_UNKNOWN_REASON：所有请求的评论更新均未能保存，即使其他演示文稿更改可能已提交。