انتقل إلى المحتوى الرئيسي

المقدمة

قم بتحميل وإدارة الملفات في التخزين السحابي مع تحسين تلقائي.

🎯 ماذا يفعل هذا الموديل؟​

يتيح لك موديل FileUploading تحميل واسترجاع وحذف الملفات في تخزين OneEntry السحابي - الصور، PDF، الفيديوهات، المستندات، وأي نوع من الملفات مع تحسين تلقائي وتوصيل عبر CDN.

فكر في الأمر كمدير تخزين سحابي خاص بك - تقوم بتحميل الملفات مرة واحدة، وOneEntry يخزنها، ويحسن الصور تلقائيًا، ويقدمها بسرعة عبر CDN.

📖 شرح بسيط​

تخيل أنك تبني تطبيقًا حيث يمكن للمستخدمين:

  • 📸 تحميل صور الملف الشخصي - إعادة الحجم وتحسين تلقائي
  • 📄 تحميل المستندات - تخزين PDF وDOC بأمان
  • 🖼️ تحميل صور المنتجات - صور متعددة لكل منتج
  • 🎥 تحميل الفيديوهات - تخزين وبث محتوى الفيديو
  • 📎 تحميل المرفقات - أي نوع من الملفات

بدلاً من إدارة التخزين الخاص بك:

  • ✅ قم بتحميل الملفات إلى سحابة OneEntry
  • ✅ تحسين تلقائي للصور (إعادة الحجم، ضغط)
  • ✅ توصيل سريع عبر CDN في جميع أنحاء العالم
  • ✅ تنظيم حسب نوع الكيان (منتج، مستخدم، صفحة)
  • ✅ الحصول على روابط تحميل على الفور
  • ✅ حذف الملفات عند عدم الحاجة إليها

مثال من العالم الحقيقي:

بدون FileUploading (يدوي):
- إعداد دلو AWS S3 ❌
- تكوين CDN ❌
- كتابة كود تحسين الصور ❌
- إدارة أذونات الملفات ❌
- توليد روابط موقعة ❌

مع FileUploading (تلقائي):
- تحميل الملف → الحصول على رابط التحميل ✅
- الصور محسنة تلقائيًا ✅
- توصيل CDN مدمج ✅
- إدارة ملفات سهلة ✅

✨ المفاهيم الأساسية​

ما هو تحميل الملفات؟​

تحميل الملفات هو تخزين الملفات في التخزين السحابي:

  • تحميل - إرسال الملف إلى سحابة OneEntry
  • التخزين - الملفات مخزنة بأمان في السحابة
  • CDN - توصيل سريع من الخوادم القريبة من المستخدمين
  • التحسين - الصور مضغوطة ومعدلة تلقائيًا
  • الرابط - الحصول على رابط تحميل دائم

أنواع الملفات المدعومة​

قم بتحميل أي نوع من الملفات:

الفئةأنواع الملفاتالتحسين التلقائي
الصورJPG، PNG، GIF، WebP، SVGنعم (إعادة الحجم، ضغط)
المستنداتPDF، DOC، DOCX، XLS، XLSXلا (تخزين كما هي)
الفيديوهاتMP4، MOV، AVI، WebMلا (تخزين كما هي)
الأرشيفاتZIP، RAR، TAR، GZلا (تخزين كما هي)
أخرىأي نوع من الملفاتلا (تخزين كما هي)

تحسين الصور​

عند تحميل الصور، يمكن لـ OneEntry:

  • 📐 إعادة الحجم - تقليل الأبعاد (على سبيل المثال، الحد الأقصى 1920 بكسل عرض)
  • 🗜️ ضغط - تقليل حجم الملف (أصغر، أسرع)
  • 🖼️ تنسيق - تحويل إلى تنسيق مثالي (WebP)
  • 📱 استجابة - إنشاء أحجام متعددة

مثال:

الأصلي: 5MB، 4000x3000 بكسل
↓ (تحسين تلقائي)
المحسن: 200KB، 1920x1440 بكسل

📋 ما تحتاج إلى معرفته​

معلمات التحميل​

عند تحميل الملفات، يمكنك تحديد:

await FileUploading.upload(file, {
  entity: 'product',     // نوع الكيان (مطلوب)
  id: 123,               // معرف الكيان (اختياري)
  type: 'image',         // تلميح نوع الملف (اختياري)
  width: 1920,           // الحد الأقصى للعرض للصور (اختياري)
  height: 1080,          // الحد الأقصى للارتفاع للصور (اختياري)
  compress: true         // ضغط الصور (اختياري)
});

شرح المعلمات:

  • file - كائن الملف (من الإدخال أو السحب والإفلات)
  • entity - الفئة: product، page، block، user، form، general
  • id - معرف الكيان لربط الملف به (على سبيل المثال، معرف المنتج)
  • type - تلميح نوع الملف (عادة ما يتم اكتشافه تلقائيًا)
  • width - الحد الأقصى للعرض بالبكسل (للصور فقط)
  • height - الحد الأقصى للارتفاع بالبكسل (للصور فقط)
  • compress - تمكين الضغط (للصور فقط)

استجابة التحميل​

بعد التحميل، ستحصل على:

{
  filename: "abc123-photo.jpg",              // اسم الملف الفريد
  downloadLink: "https://cdn.../photo.jpg",  // رابط CDN
  size: 204800,                              // حجم الملف (بايت)
}

الحقول المهمة:

  • downloadLink - استخدم هذا الرابط في علامات <img>، <a>، <video>
  • filename - احفظ هذا لحذف الملف لاحقًا
  • size - حجم الملف بالبايت (204800 بايت = 200KB)

أفضل الممارسات لتنظيم الملفات​

نظم الملفات حسب نوع الكيان

خيارات تحسين الصور​

تحكم في كيفية تحسين الصور:

الخيارماذا يفعلالمثال
widthالحد الأقصى للعرض (يحافظ على نسبة العرض إلى الارتفاع)width: 1920
heightالحد الأقصى للارتفاع (يحافظ على نسبة العرض إلى الارتفاع)height: 1080
compressتقليل حجم الملفcompress: true

نسبة العرض إلى الارتفاع محفوظة:

الأصلي: 4000x3000 (نسبة 4:3)
مع العرض: 800
النتيجة: 800x600 (لا تزال 4:3)

حذف الملفات​

قم دائمًا بتوفير الكيان، المعرف، واسم الملف للحذف:

await FileUploading.delete({
  entity: 'product',
  id: productId,
  filename: 'abc123-photo.jpg'
});

لماذا الثلاثة جميعًا؟ يتم تنظيم الملفات حسب الكيان → المعرف → اسم الملف.

📊 جدول مرجعي سريع - الطرق​

الطريقةماذا تفعلمتى تستخدم
upload()تحميل ملف إلى التخزين السحابييقوم المستخدم بتحميل صورة، مستند
getFile()الحصول على معلومات الملف (الحجم، النوع، الرابط)تحقق مما إذا كان الملف موجودًا
delete()حذف ملف من التخزينإزالة الملفات القديمة

❓ الأسئلة الشائعة (FAQ)​

ما هي أنواع الملفات التي يمكنني تحميلها؟​

أي نوع من الملفات مدعوم:

  • الصور: JPG، PNG، GIF، WebP، SVG، BMP، TIFF
  • المستندات: PDF، DOC، DOCX، XLS، XLSX، PPT، TXT
  • الفيديوهات: MP4، MOV، AVI، WebM، MKV
  • الأرشيفات: ZIP، RAR، TAR، GZ
  • أخرى: أي نوع من الملفات

فقط الصور يتم تحسينها تلقائيًا. يتم تخزين الملفات الأخرى كما هي.

ما هو الحد الأقصى لحجم الملف؟​

تحقق من حدود خطة OneEntry الخاصة بك. عادةً:

  • الخطة المجانية: 5MB لكل ملف
  • الخطط المدفوعة: 50MB - 100MB لكل ملف

أفضل ممارسة: تحسين الصور قبل التحميل لتقليل الحجم.

هل يتم تخزين الملفات بشكل دائم؟​

نعم، يتم تخزين الملفات حتى تقوم بحذفها يدويًا باستخدام FileUploading.delete().

مهم: قم بتنظيف الملفات غير المستخدمة لتوفير مساحة التخزين.

هل يمكنني تحميل الملفات من الواجهة الأمامية (المتصفح)؟​

نعم! استخدم إدخال الملف أو السحب والإفلات.

كيف يمكنني التحقق من صحة الملفات قبل التحميل؟​

تحقق من نوع الملف وحجمه.

هل يمكنني الحصول على قائمة بجميع الملفات المحملة لكائن؟​

ليس مباشرةً مع هذه SDK. تحتاج إلى:

  1. تتبع أسماء الملفات عند التحميل (احفظها في قاعدة البيانات)
  2. استخدم واجهة برمجة تطبيقات OneEntry Admin لعرض الملفات

أفضل ممارسة: احفظ أسماء الملفات المحملة في قاعدة البيانات الخاصة بك.

كيف أتعامل مع أخطاء التحميل؟​

استخدم دائمًا try/catch.

هل يمكنني تحميل الملفات إلى CDN مباشرة؟​

لا، يتم تحميل الملفات عبر واجهة برمجة تطبيقات OneEntry، والتي:

  1. تتحقق من صحة الملف
  2. تحسن الصور (إذا تم تمكينها)
  3. تخزن في السحابة
  4. تعيد رابط CDN

هذا يضمن الأمان والتحسين.

ماذا يحدث للملفات إذا قمت بحذف كائن (منتج، مستخدم)؟​

تظل الملفات في التخزين حتى إذا تم حذف الكائن.

أفضل ممارسة: احذف الملفات قبل حذف الكائن.

هل يمكنني تغيير حجم الصور إلى أبعاد دقيقة؟​

لا، يتم دائمًا الحفاظ على نسبة العرض إلى الارتفاع لمنع التشويه.

كيف يعمل:

  • تقوم بتعيين width: 800، height: 600
  • يتم تغيير حجم الصورة لتناسب داخل 800x600
  • يتم الحفاظ على نسبة العرض إلى الارتفاع

مثال:

الأصلي: 1000x500 (نسبة 2:1)
مع العرض: 800، الارتفاع: 600
النتيجة: 800x400 (لا تزال 2:1، تناسب داخل 800x600)

💡 ملاحظات مهمة​

أمان الملفات​

الملفات المحملة متاحة للجمهور عبر CDN:

  • ✅ رائعة للصور، المستندات العامة
  • ⚠️ لا تقم بتحميل ملفات حساسة (كلمات المرور، البيانات الخاصة)

لملفات خاصة:

  • استخدم واجهة برمجة تطبيقات OneEntry Admin مع المصادقة
  • أو نفذ التحكم في الوصول الخاص بك

حدود التخزين​

راقب استخدام التخزين الخاص بك:

  • كل خطة لها حدود تخزين
  • قم بتنظيف الملفات غير المستخدمة بانتظام
  • قم بضغط الصور قبل التحميل

نصائح لتحسين الصور​

لأفضل النتائج:

  • ✅ قم بتحميل النسخ الأصلية عالية الجودة (دع OneEntry يقوم بالتحسين)
  • ✅ استخدم compress: true للصور على الويب
  • ✅ قم بتعيين الأبعاد المناسبة (على سبيل المثال، 1920 بكسل للصور الرئيسية، 500 بكسل للصور المصغرة)
  • ❌ لا تقم بتحميل صور مضغوطة مسبقًا (فقدان الجودة)

الأحجام الموصى بها:

  • صور الملف الشخصي: 500x500
  • صور المنتجات: 1920x1920
  • لافتات البطل: 1920x1080
  • الصور المصغرة: 300x300

🎓 أفضل الممارسات​

  • تحقق من نوع الملف وحجمه قبل التحميل
  • اربط الملفات بمعرفات الكيانات للتنظيم
  • قم بتمكين الضغط للصور على الويب
  • تعامل مع أخطاء التحميل بشكل لطيف
  • احفظ أسماء الملفات لحذف الملفات لاحقًا
  • قم بتنظيف الملفات غير المستخدمة بانتظام
  • عرض تقدم التحميل للمستخدمين

تعريف موديل FileUploading​


const { FileUploading } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

🔗 الوثائق ذات الصلة​