العمل مع تعليقات إكسل – دليل واجهة برمجة تطبيقات Aspose.Cells Cloud

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

متطلبات ما قبل التشغيل

• حساب نشط في Aspose.Cells Cloud.
• رمز وصول (access token) صالح تم الحصول عليه عبر بروتوكول OAuth 2.0.
• إصدار واجهة برمجة التطبيقات v3.0 (النقاط النهائية المستخدمة في هذا الدليل تنتمي إلى هذا الإصدار).
• اختياري: استخدام SDK الخاص بـ Aspose.Cells للغة البرمجة المفضّلة لديك لتبسيط بناء الطلبات.

الإصدارة

تستهدف الأمثلة أدناه واجهة برمجة تطبيقات Aspose.Cells Cloud REST API الإصدار 3.0. وقد تُقدّم الإصدارات المستقبلية من واجهة برمجة التطبيقات معلمات إضافية أو تُعدّل هياكل الاستجابات؛ لذا يُوصى دائمًا بالرجوع إلى مرجع واجهة برمجة التطبيقات الأحدث للحصول على التفاصيل المُحدَّثة.

إضافة تعليق

لإضافة تعليق، أرسل طلبًا من نوع POST إلى النقطة النهائية التالية:

POST https://api.aspose.cloud/v3.0/cells/{file}/worksheets/{sheet}/comments
Authorization: Bearer {access_token}
Content-Type: application/json

المعلمات في مسار الطلب

مخطط جسم الطلب

مثال على جسم الطلب

{
  "CellName": "B2",
  "Comment": "يحتاج مراجعة",
  "Author": "John Doe"
}

مثال على استجابة ناجحة (200 OK)

{
  "Code": 200,
  "Status": "OK",
  "Comment": {
    "CellName": "B2",
    "Author": "John Doe",
    "HtmlComment": "يحتاج مراجعة",
    "Note": "يحتاج مراجعة"
  }
}

أكواد الأخطاء الشائعة

جلب التعليقات

لجلب جميع التعليقات من ورقة عمل:

GET https://api.aspose.cloud/v3.0/cells/{file}/worksheets/{sheet}/comments
Authorization: Bearer {access_token}

المعلمات في مسار الطلب

مثال على الاستجابة

{
  "Code": 200,
  "Status": "OK",
  "Comments": [
    {
      "CellName": "A1",
      "Author": "Alice",
      "HtmlComment": "القيمة الأولية",
      "Note": "القيمة الأولية"
    },
    {
      "CellName": "B2",
      "Author": "John Doe",
      "HtmlComment": "يحتاج مراجعة",
      "Note": "يحتاج مراجعة"
    }
  ]
}

تحديث تعليق

لتعديل تعليق موجود، أرسل طلبًا من نوع PUT. ويُعرّف التعليق بـ فهرسه ضمن مجموعة التعليقات في ورقة العمل (مع بدء العد من 0).

PUT https://api.aspose.cloud/v3.0/cells/{file}/worksheets/{sheet}/comments/{commentIndex}
Authorization: Bearer {access_token}
Content-Type: application/json

المعلمات في مسار الطلب

مخطط جسم الطلب

مثال على جسم الطلب

{
  "Comment": "نص ملاحظة محدّث",
  "Author": "John Doe"
}

وتكون الاستجابة بنفس الهيكل المستخدم في استجابة إضافة تعليق.

حذف تعليق

لحذف تعليق واحد حسب فهرسه:

DELETE https://api.aspose.cloud/v3.0/cells/{file}/worksheets/{sheet}/comments/{commentIndex}
Authorization: Bearer {access_token}

المعلمات في مسار الطلب

ويُعاد الاستجابة التالية عند نجاح الحذف:

{
  "Code": 200,
  "Status": "OK"
}

حذف جميع التعليقات

لمسح جميع التعليقات من ورقة عمل:

DELETE https://api.aspose.cloud/v3.0/cells/{file}/worksheets/{sheet}/comments
Authorization: Bearer {access_token}

المعلمات في مسار الطلب

إرشادات معالجة الأخطاء

• 404 Not Found – تحقق من أن معرّف المصنف واسم ورقة العمل وفهرس التعليق صحيحة.
• 400 Bad Request – تحقق من صحة بناء JSON ووجود الحقول الإلزامية (CellName, Comment).
• 429 Too Many Requests – نفّذ آلية تأخير أسّية (exponential back-off) واحترم رأس الاستجابة Retry-After.

الملخّص

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

لمزيد من المعلومات حول العمل مع عناصر جداول البيانات الأخرى، راجع الدليل الخاص بـ العمل مع الخلايا.