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

تتيح "العروض التقديمية من Google" للمستخدمين التعاون من خلال إضافة تعليقات على الشرائح وعناصر الصفحة.

يوضّح هذا المستند كيف يمكنك استخدام Google Slides API لقراءة التعليقات أو إنشائها أو الرد عليها أو تعديلها أو حذفها آليًا.

قراءة التعليقات

عند استخدام طريقة get على المورد presentations لاسترداد عرض تقديمي، يتم تلقائيًا حذف سلاسل المحادثات والروابط المؤدية إلى التعليقات.

لتضمين التعليقات في الردّ، اضبط معلَمة البحث 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)

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

• تمثّل هذه السمة مصفوفة comments عامة تحتوي على عناصر CommentThread.
• مصفوفة commentAnchors تحتوي على عناصر CommentAnchor التي تربط معرّفات مرساة التعليقات بمواقع الصفحات أو عناصر الصفحات (مراسي العناصر).

قراءة التعليقات على صفحة معيّنة

يمكنك أيضًا استرداد التعليقات والمرتكزات لصفحة معيّنة باستخدام الطريقة pages.get في المرجع presentations.pages. اضبط مَعلمة طلب البحث 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: المعرّف الخاص بكائن صفحة شريحة أو عنصر صفحة (مثل شكل أو جدول) يتم ربط التعليق به.
• 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.

يمكنك أيضًا إعادة تعيين سلسلة محادثات تعليق من خلال تحديد assigneeEmail جديد في الكائن Post.

يوضّح نموذج 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. لا يمكنك حذف سلسلة تعليقات إلا إذا كنت كاتب headPost السلسلة في عنصر CommentThread.

• حذف ردّ: لحذف ردّ معيّن Post من CommentThread، استخدِم عنصر DeleteCommentReplyRequest. يمكنك حذف الردود التي كتبتها فقط. لا يمكنك حذف مشاركات الردود التي تحتوي على commentAction أو assigneeEmail.

يوضّح نموذج JSON التالي كيفية حذف سلسلة محادثات تعليقات:

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

حالة تعديل التعليق

قد تحدث حالات إخفاق جزئي في الطلبات التي تتطلّب حفظ سلاسل محادثات التعليقات (مثل إدراج تعليقات أو إضافة ردود). في هذه الحالات، قد يتم حفظ التغييرات في نموذج العرض (مثل تعديل محتوى الشرائح أو الخلفيات) بنجاح، ولكن قد يتعذّر حفظ التعليقات المرتبطة بها.

يمكنك التأكّد من تطبيق تعديلات التعليقات بنجاح من خلال التحقّق من الحقل commentUpdateState في نص الاستجابة للطريقة presentations.batchUpdate. يتم تمثيل الحقل باستخدام عنصر CommentUpdateState.

يتم عرض الحالات التالية في CommentUpdateState:

• ‫NO_UPDATES_REQUESTED: لم يتم طلب أي تعديلات على التعليقات في عملية الدفعات.
• ALL_SAVED: تم تطبيق جميع التعديلات المطلوبة على التعليقات بنجاح.
• ‫ALL_FAILED_UNKNOWN_REASON: تعذّر حفظ جميع التعديلات المطلوبة على التعليقات، على الرغم من أنّه قد تم حفظ تغييرات أخرى على العرض التقديمي.