จัดการความคิดเห็น

Google ชีตช่วยให้ผู้ใช้ทำงานร่วมกันได้โดยการเพิ่มความคิดเห็นในเซลล์ที่เฉพาะเจาะจง

เอกสารนี้แสดงวิธีใช้ Google Sheets API เพื่ออ่าน สร้าง ตอบกลับ อัปเดต หรือลบความคิดเห็นแบบเป็นโปรแกรม

อ่านความคิดเห็น

เมื่อใช้เมธอด get ในทรัพยากร spreadsheets เพื่อดึงข้อมูลสเปรดชีต ระบบจะละเว้นเธรดความคิดเห็นและแองเคอร์โดยค่าเริ่มต้น

หากต้องการรวมความคิดเห็นไว้ในการตอบกลับ ให้ตั้งค่าพารามิเตอร์การค้นหา 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)

ในการตอบกลับ ระบบจะแสดงความคิดเห็นใน 2 ตำแหน่งดังนี้

  • อาร์เรย์ comments ส่วนกลางที่มีออบเจ็กต์ CommentThread
  • อาร์เรย์ sheets.commentAnchors ที่มี CommentAnchor ออบเจ็กต์ซึ่งจับคู่รหัสแองเคอร์ความคิดเห็นกับตำแหน่งเซลล์ (ช่วงตารางกริด)

กรองความคิดเห็นตามช่วงหรือชีต

เมื่อดึงข้อมูลสเปรดชีต คุณสามารถกรองข้อมูลที่แสดงผลได้โดยระบุ ช่วง (โดยใช้ ranges พารามิเตอร์การค้นหาในเมธอด spreadsheets.get) หรือชีต (โดยใช้ dataFilters ฟิลด์ในเนื้อหาคำขอของเมธอด spreadsheets.getByDataFilter)

  • หากกรองตามช่วงหรือชีต: ระบบจะแสดงผลเฉพาะเธรดความคิดเห็นที่แองเคอร์ ภายในช่วงหรือชีตที่ระบุ โดยจะไม่รวมความคิดเห็นที่ไม่ได้แองเคอร์ (เช่น ความคิดเห็นที่ลบพิกัดเซลล์เดิมไปแล้ว)
  • หากไม่กรองตามช่วงหรือชีต: ระบบจะแสดงผลเธรดความคิดเห็นทั้งหมด รวมถึง ความคิดเห็นที่ไม่ได้แองเคอร์

ตัวอย่างการตอบกลับ

ตัวอย่างการตอบกลับ JSON ต่อไปนี้แสดงเธรดความคิดเห็นที่แองเคอร์กับเซลล์ A1 (แถว 0, คอลัมน์ 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 ต่อไปนี้แสดงวิธีเพิ่มเธรดความคิดเห็นที่ไม่ได้กำหนดให้กับเซลล์ B2 (แถว 1, คอลัมน์ 1) ในชีตที่มีรหัส 0

{
  "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 การตอบกลับ และสามารถระบุ a commentAction ได้ (รวมถึงการดำเนินการเพื่อ RESOLVE หรือ REOPEN เธรดความคิดเห็น) ซึ่งแสดงโดยออบเจ็กต์ CommentActionType

นอกจากนี้ คุณยังกำหนดเธรดความคิดเห็นใหม่ได้โดยระบุ assigneeEmail ใหม่ในออบเจ็กต์ Post

ตัวอย่าง 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."
      }
    }
  ]
}

ลบความคิดเห็นและการตอบกลับ

คุณมี 2 ตัวเลือกในการลบความคิดเห็นและการตอบกลับ

  • ลบเธรดความคิดเห็น: หากต้องการนำ CommentThreadทั้งหมดออก ให้ใช้ออบเจ็กต์ DeleteCommentRequest คุณจะลบเธรดความคิดเห็นได้ก็ต่อเมื่อคุณเป็นผู้เขียนของ เธรด headPost ในออบเจ็กต์ CommentThread

  • ลบการตอบกลับ: หากต้องการลบการตอบกลับที่เฉพาะเจาะจง Post จาก CommentThread ให้ใช้ DeleteCommentReplyRequest ออบเจ็กต์ คุณจะลบได้เฉพาะการตอบกลับที่คุณเขียนเท่านั้น และไม่สามารถลบโพสต์การตอบกลับที่มี commentAction หรือ assigneeEmail

ตัวอย่าง JSON ต่อไปนี้แสดงวิธีลบเธรดความคิดเห็น

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

สถานะการอัปเดตความคิดเห็น

คำขอที่ต้องบันทึกเธรดความคิดเห็น (เช่น การแทรกความคิดเห็นหรือการเพิ่มการตอบกลับ) อาจพบข้อผิดพลาดบางส่วน ในกรณีเหล่านี้ การเปลี่ยนแปลงโมเดลสเปรดชีต (เช่น การอัปเดตค่าเซลล์หรือการเพิ่มชีต) อาจดำเนินการสำเร็จ แต่ระบบอาจบันทึกความคิดเห็นที่เกี่ยวข้องไม่สำเร็จ

คุณสามารถตรวจสอบว่าการอัปเดตความคิดเห็นดำเนินการสำเร็จหรือไม่โดยดู commentUpdateState ฟิลด์ในเนื้อหาการตอบกลับของเมธอด spreadsheets.batchUpdate ซึ่งแสดงโดยออบเจ็กต์ CommentUpdateState

ระบบจะแสดงสถานะต่อไปนี้ใน CommentUpdateState

  • NO_UPDATES_REQUESTED: ไม่มีการขออัปเดตความคิดเห็นในการดำเนินการแบบเป็นชุด
  • ALL_SAVED: การอัปเดตความคิดเห็นที่ขอทั้งหมดดำเนินการสำเร็จ
  • ALL_FAILED_UNKNOWN_REASON: ระบบบันทึกการอัปเดตความคิดเห็นที่ขอทั้งหมดไม่สำเร็จ แม้ว่าการเปลี่ยนแปลงสเปรดชีตอื่นๆ อาจดำเนินการแล้วก็ตาม