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

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

ملاحظة: في ملفات الكائن الثنائي الكبير (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، يُرجى الرجوع إلى صفحة المنطقة والمصنِّفات

يعرض المثال التالي سلسلة ارتساء 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.