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

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