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

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

ملاحظة: في ملفات Blob، لا تتيح Google Drive API سوى التعليقات غير المرتبطة بعنصر. لا تتوفّر التعليقات المرتبطة في ملفات Blob أو ملفات محرِّر "مستندات Google".

يتم إرفاق الردود بالتعليقات، وهي تمثّل ردّ المستخدم على التعليق. تتيح واجهة برمجة التطبيقات Drive API للمستخدمين إضافة تعليقات وردود على المستندات التي أنشأها تطبيقك. ويُعرف التعليق الذي يتضمّن ردودًا باسم مناقشة.

إضافة تعليق غير مرتبط

لإضافة تعليق غير مرتبط بعنصر إلى مستند، استخدِم الطريقة comments.create مع المَعلمة fileId ومورد comments يحتوي على التعليق.

يتم إدراج التعليق كنص عادي، ولكنّ نص الردّ يقدّم حقل htmlContent يحتوي على محتوى منسَّق للعرض.

ملاحظة مهمة: ننصحك بالتحقّق من أنّ المستخدم لديه الأذونات الصحيحة لإضافة التعليقات. بالإضافة إلى ذلك، يمكن لصانع التعليق أو الرد فقط حذفه أو تعديله. تحدث الأخطاء عندما يحاول مستخدم لا يملك دور صانع محتوى حذف تعليق أو تعديله. لتجنُّب حدوث هذه الأخطاء، تحقّق من حقل author.me في مرجع التعليقات للتأكّد من أنّ المستخدم الذي يقدّم الطلب هو كاتب التعليق، ثم تحقّق من أذوناته المتعلّقة بالتعليق.

إضافة ردّ على تعليق

لإضافة ردّ على تعليق، استخدِم الأسلوب replies.create مع المَعلمة fileId والتعليق ومورد replies الذي يحتوي على الردّ.

يتم إدراج الردّ كنص عادي، ولكنّ نص الاستجابة يقدّم حقل htmlContent يحتوي على محتوى منسَّق للعرض.

إضافة تعليق مرتبط إلى أحدث نسخة من مستند

عند إضافة تعليق، قد تحتاج إلى ربطه بمنطقة في الملف. تحدِّد المرجع نسخة الملف والمنطقة في الملف التي يشير إليها التعليق. يحدِّد المورد comments الحقل anchor كسلسلة JSON.

ملاحظة: في ملفات Blob، لا تتيح Drive API سوى التعليقات غير المرتبطة بعنصر. لا تتوفّر التعليقات المرتبطة في ملفات Blob أو ملفات محرِّر "مستندات Google".

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

لإضافة تعليق مرتبط:

1. (اختياري). استخدِم الطريقة revisions.list لعرض كل revisionID لمستند معيّن. اتّبِع هذه الخطوة فقط إذا كنت تريد ربط تعليق بأيّ مراجعة غير المراجعة الأخيرة. إذا كنت تريد استخدام أحدث نسخة، استخدِم head للعنصر revisionID.

2. استخدِم الطريقة comments.create مع المَعلمة fileID ومورد comments يحتوي على التعليق، وسلسلة عنصر ربط JSON تحتوي على revisionID (r) والمنطقة (a).

تعتمد طريقة تحديد منطقة على نوع محتوى المستند الذي تعمل عليه. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تحديد منطقة.

ملاحظة: ننصحك بالتحقّق من أنّ المستخدم لديه الأذونات الصحيحة لإضافة التعليقات. بالإضافة إلى ذلك، يمكن لصانع التعليق أو الرد فقط حذفه أو تعديله. تحدث الأخطاء عندما يحاول مستخدم لا يملك دور صانع محتوى حذف تعليق أو تعديله. لتجنُّب حدوث هذه الأخطاء، تحقّق من حقل author.me في مرجع التعليقات.

تحديد منطقة

كما ذكرنا سابقًا، تحتوي سلسلة إشارة مرجعية JSON على revisionID (r) و region (a). وregion (a) هي مصفوفة JSON تحتوي على تصنيفات منطقة تحدد التنسيق والموقع الجغرافي الذي يتمّ ربط التعليق به. قد يكون المصنِّف مستطيلاً ثنائي الأبعاد لصورة أو سطر نص في مستند أو مدة زمنية في فيديو. لتحديد منطقة، اختَر تصنيف المنطقة الذي يتطابق مع نوع المحتوى الذي تحاول الربط به. على سبيل المثال، إذا كان المحتوى نصيًا، من المرجّح أن تستخدم إما مصنّف المنطقة txt أو line.

للحصول على قائمة بفئات المناطق في Drive API، يُرجى الرجوع إلى فئات المنطقة.

يوضّح المثال التالي سلسلة ربط JSON تربط التعليقات بالسطور في منطقتَين منفصلتَين من المستند:

• تبدأ المنطقة الأولى في السطر 12 ('n':12) وتمتد على ثلاثة أسطر ('l':3).
• لا تغطي المنطقة الثانية سوى السطر 18 ('n':18, 'l':1`).

    {
      'r': 'REVISION_ID',
      'a': [
      {
        'line':
        {
          'n': 12,
          'l': 3,
        }
      },
      {
        'line':
        {
          'n': 18,
          'l': 1,
        }
      }]
    }

استبدِل REVISION_ID بـ head أو بمعرّف مراجعة معيّنة.

ملاحظة مهمة: إذا كان تطبيقك يتيح للمستخدمين تعديل نُسخ متعددة من مستند ومشاركتها، قد لا تعود التعليقات على النُسخ القديمة تنطبق على الموقع المرتبط. لذلك، يجب الإشارة بوضوح في واجهة المستخدم إلى النسخة التي ينتمي إليها كل تعليق.

حلّ تعليق

استخدِم الطريقة comment.update لضبط السمة resolved في مورد comments على true عند معالجة تعليق.

عندما يضبط تطبيقك السمة resolved على true، من المفترض أن تشير واجهة المستخدم إلى أنّه تمّت معالجة التعليق. على سبيل المثال، قد يفعل تطبيقك ما يلي:

• يمكنك منع المزيد من الردود وتعتيم جميع الردود السابقة بالإضافة إلى التعليق الأصلي.
• إخفاء التعليقات التي تم حلّها

حذف تعليق

استخدِم طريقة comments.delete ل حذف التعليقات. عند حذف تعليق، يضع Drive علامة "deleted": "true" على مصدر التعليق.

عرض التعليقات

استخدِم الطريقة comments.list لعرض التعليقات. إذا أردت تضمين التعليقات المحذوفة في النتائج، اضبط الحقل includedDeleted على true.