التعليقات هي ملاحظات مقدَّمة من المستخدم حول أحد الملفات، مثل قارئ مستند معالجة الكلمات الذي يقترح كيفية إعادة صياغة جملة. يتوفّر نوعان من التعليقات: التعليقات الثابتة والتعليقات غير الثابتة. ويرتبط التعليق الثابت بموقع جغرافي محدّد، مثل جملة في مستند يعالج الكلمات، ضمن نسخة معيّنة من مستند. وعلى العكس من ذلك، يرتبط التعليق غير الثابت فقط بالوثيقة.
يتم إرفاق الردود بالتعليقات وتمثّل رد المستخدم على التعليق. تسمح واجهة برمجة تطبيقات Drive للمستخدمين بإضافة تعليقات وردود على المستندات التي أنشأها تطبيقك. يُعرف التعليق الذي يتضمّن ردودًا مجتمعةً باسم مناقشة.
إضافة تعليق غير ثابت
لإضافة تعليق غير ثابت إلى مستند، عليك طلب الإجراء comments.create
مع المَعلمة fileId
ومورد comments
يحتوي على التعليق.
يتم إدراج التعليق كنص عادي، إلا أنّ نص الاستجابة يوفّر
حقل htmlContent
يحتوي على محتوى تم تنسيقه للعرض.
إضافة رد على تعليق
لإضافة رد على تعليق، عليك استدعاء طريقة
replies.create
مع التعليق،
ومَعلمة fileId
ومورد replies
يحتوي على الرد.
يتم إدراج الردّ كنص عادي، إلا أنّ نص الاستجابة يوفّر حقل htmlContent
يحتوي على محتوى منسّق للعرض.
إضافة تعليق ثابت إلى أحدث نسخة سابقة من مستند
عند إضافة تعليق، قد ترغب في ربطه بمنطقة في الملف. تحدّد علامة الارتساء مراجعة الملف والمنطقة التي يشير إليها التعليق. يحدّد مورد comments
الحقل
anchor
كسلسلة JSON.
لإضافة تعليق ثابت:
(اختياريّ): يمكنك استدعاء الطريقة
revisions.list
لإدراج كلrevisionID
للمستند. اتبع هذه الخطوة فقط إذا كنت تريد تثبيت تعليق على أي مراجعة أخرى بخلاف أحدث مراجعة. إذا أردت استخدام أحدث نسخة، استخدِمhead
للسمةrevisionID
.عليك استدعاء الإجراء
comments.create
مع المعلَمةfileID
، وموردcomments
الذي يحتوي على التعليق، وسلسلة ارتساء JSON تحتوي علىrevisionID
(r
) والمنطقة (a
).
تعتمد طريقة تحديد المنطقة على نوع محتوى المستند الذي تتعامل معه. لمزيد من المعلومات، يُرجى الرجوع إلى مقالة تحديد منطقة.
تحديد منطقة
كما ذكرنا سابقًا، تحتوي سلسلة ارتساء 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
.