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

مقدمة

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

مزيد من المعلومات حول واجهة مستخدم الوحدة https://doc.oneentry.cloud/docs/attributes/types/#File

🎯 ماذا تفعل هذه الوحدة؟​

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

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

📖 شرح بسيط​

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

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

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

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

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

Without FileUploading (manual):
- Set up AWS S3 bucket ❌
- Configure CDN ❌
- Write image optimization code ❌
- Manage file permissions ❌
- Generate signed URLs ❌

With FileUploading (automatic):
- Upload file → Get download URL ✅
- Images auto-optimized ✅
- CDN delivery built-in ✅
- Easy file management ✅

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

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

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

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

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

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

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

تحسين الصور​

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

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

مثال:

Original: 5MB, 4000x3000px
↓ (auto-optimize)
Optimized: 200KB, 1920x1440px

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

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

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

await FileUploading.upload(file, {
  entity: 'product',     // Entity type (required)
  id: 123,               // Entity ID (optional)
  type: 'image',         // File type hint (optional)
  width: 1920,           // Max width for images (optional)
  height: 1080,          // Max height for images (optional)
  compress: true         // Compress images (optional)
});

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

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

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

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

{
  filename: "abc123-photo.jpg",              // Unique filename
  downloadLink: "https://cdn.../photo.jpg",  // CDN URL
  size: 204800,                              // File size (bytes)
}

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

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

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

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

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

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

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

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

Original: 4000x3000 (4:3 ratio)
With width: 800
Result: 800x600 (still 4:3 ratio)

حذف الملفات​

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

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
  • يتم الحفاظ على نسبة العرض إلى الارتفاع

مثال:

Original: 1000x500 (2:1 ratio)
With width: 800, height: 600
Result: 800x400 (still 2:1 ratio, fits within 800x600)

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

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

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

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

لملفات خاصة:

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

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

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

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

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

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

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

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

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

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

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

تعريف وحدة FileUploading​


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

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