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

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

ملاحظة: لا تتيح "واجهة برمجة تطبيقات Drive" استخدام التعليقات على مستوى الملفات إلا على ملفات الكائن الثنائي الكبير (blob). لا تتوافق التعليقات الثابتة على ملفات الكائن الثنائي الكبير (blob) أو ملفات "أدوات تحرير مستندات Google" مع هذه الميزة.

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

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

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

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

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

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

لإضافة ردّ على تعليق، يجب استدعاء طريقة replies.create مع التعليق ومَعلمة fileId ومورد reply يحتوي على الردّ.

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

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

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

ملاحظة: لا تتيح "واجهة برمجة تطبيقات Drive" استخدام التعليقات على مستوى الملفات إلا على ملفات الكائن الثنائي الكبير (blob). التعليقات الثابتة على ملفات 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.