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

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

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