使用者可以在 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陣列，內含CommentAnchor物件，可將註解錨點 ID 對應至網頁或網頁元素位置 (物件錨點)。
閱讀特定頁面的留言
您也可以使用 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"
}
建立及管理留言
您可以使用 batchUpdate 方法，以程式輔助方式新增、編輯及刪除 presentations 資源的註解或回覆。
執行涉及留言的批次更新時，請監控可能發生的部分失敗情況。詳情請參閱留言更新狀態。
插入註解
如要在簡報中插入留言串，請使用
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只有討論串的作者才能刪除討論串的headPostCommentThread物件。刪除回覆：如要從
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：所有要求的註解更新都無法儲存，即使其他簡報變更可能已提交也一樣。