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

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

ملاحظة: في ملفات 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.