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

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

ملاحظة: في ملفات blob، لا تتيح Google Drive API سوى التعليقات غير الثابتة. لا يمكن استخدام التعليقات الثابتة على ملفات blob أو ملفات أدوات تحرير "مستندات Google".

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

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

لإضافة تعليق غير ثابت إلى مستند، عليك طلب الإجراء 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) والمنطقة (a). المنطقة (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.