إدارة التعليقات

معاينة المطور: يتوفّر كجزء من برنامج الاستخدام المبكر في Google Workspace للمطوّرين، الذي يتيح استخدام ميزات معيّنة قبل إطلاقها.

يتيح Google Sheets للمستخدمين التعاون من خلال إضافة تعليقات على خلايا معيّنة.

يوضّح هذا المستند كيف يمكنك استخدام 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)

في الردّ، يتم عرض التعليقات في موضعَين:

• تمثّل هذه السمة مصفوفة 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 ويمكنه اختياريًا تحديد 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."
      }
    }
  ]
}

حذف التعليقات والردود

لحذف التعليقات والردود، لديك خياران:

• حذف سلسلة محادثات: لإزالة سلسلة محادثات بأكملها 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: تعذّر حفظ جميع التعديلات المطلوبة على التعليقات، على الرغم من أنّه قد تم حفظ تغييرات أخرى في جدول البيانات.