تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

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

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