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

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: การอัปเดตความคิดเห็นที่ขอทั้งหมดบันทึกไม่สำเร็จ แม้ว่าการเปลี่ยนแปลงสเปรดชีตอื่นๆ อาจสำเร็จแล้วก็ตาม