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

المقدمة

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

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

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

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

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

🚀 البدء السريع​

قم بتهيئة الوحدة من defineOneEntry:


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

قم بتحميل ملف واقرأ رابط التنزيل المعاد:

// upload() returns an ARRAY of uploaded files (IUploadingReturn[]).
const uploaded = await FileUploading.upload(file, {
  entity: "product",
  id: 123,
  type: "image",
  compress: true,
});

const { filename, downloadLink, size } = uploaded[0];
console.log(downloadLink); // use in <img>, <a>, <video>

لاحقًا، احذفه بواسطة اسم الملف (الكيان/المعرف يحل مجلد التخزين):

await FileUploading.delete(filename, { entity: "product", id: 123 });

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

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

تحميل الملفات هو تخزين الملفات في التخزين السحابي والحصول على رابط CDN دائم:

  • تحميل - إرسال File أو Blob إلى سحابة OneEntry
  • التخزين - يتم تخزين الملفات، وتنظيمها بواسطة entity → id → filename
  • CDN - توصيل سريع من الخوادم القريبة من المستخدمين
  • التحسين - يمكن ضغط الصور تلقائيًا وإعادة حجمها
  • الرابط - downloadLink في الاستجابة هو الرابط الدائم

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

يتم قبول أي نوع من الملفات. فقط الصور يتم تحسينها تلقائيًا؛ كل شيء آخر يتم تخزينه كما هو.

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

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

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

upload(file, fileQuery?) تأخذ الملف بالإضافة إلى كائن استعلام اختياري:

await FileUploading.upload(file, {
  entity: 'product',     // Storage folder name (optional, any string)
  id: 123,               // Entity ID (optional)
  type: 'image',         // Folder/type hint (optional, any string)
  width: 1920,           // Max width for images (optional)
  height: 1080,          // Max height for images (optional)
  compress: true,        // Compress images (optional)
});
  • file — الـ File أو Blob الذي سيتم تحميله (من إدخال أو سحب وإفلات)
  • entity — اسم المجلد الحر في التخزين (مثل product، page، user، editor — أمثلة، ليست تعداد ثابت)
  • id — معرف الكيان لربط الملف به
  • type — سلسلة تلميح نوع/مجلد حرة
  • width / height — الأبعاد القصوى للصور (يتم الحفاظ على نسبة العرض إلى الارتفاع)
  • compress — تمكين ضغط الصور

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

upload() تحل إلى مصفوفة من IUploadingReturn. كل عنصر يحتوي على:

{
  filename: "uploads/abc123-photo.jpg",      // Filename with relative path
  downloadLink: "https://cdn.../photo.jpg",  // CDN URL
  size: 204800,                              // File size in bytes
  contentType: "image/png",                  // MIME type
}
  • downloadLink — استخدم هذا الرابط في علامات <img>، <a>، <video>
  • filename — احفظه لحذف الملف لاحقًا
  • size — حجم الملف بالبايت

تحسين الصور​

بالنسبة للصور يمكنك تمرير width، height، وcompress. نسبة العرض إلى الارتفاع محفوظة دائمًا — يتم إعادة حجم الصورة لتناسب داخل الحدود المعطاة، دون تمدد.

حذف الملفات​

مرر اسم الملف أولاً؛ الكيان/المعرف/النوع يعيش في كائن الاستعلام الاختياري الذي يحل مجلد التخزين:

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

استرجاع ملف​

getFile(id, type, entity, filename, template?) تعيد كائن Response خام (ليس JSON محلل) — اتصل بـ .blob()، .arrayBuffer()، إلخ حسب الحاجة.

بناء ملف من رابط URL​

createFileFromUrl(url, filename, mimeType?) يجلب موردًا بعيدًا ويعيد File للمتصفح، مفيد لإعادة تحميل صورة بعيدة موجودة.

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

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

جميع الطرق عامة — لا حاجة لتفويض المستخدم.

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

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

أي نوع من الملفات. فقط الصور يتم تحسينها تلقائيًا (إعادة الحجم/ضغط)؛ يتم تخزين الملفات الأخرى كما هي.

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

يعتمد ذلك على حدود خطة OneEntry الخاصة بك. قم بتحسين الصور قبل التحميل للحفاظ على الأحجام منخفضة.

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

نعم — تبقى الملفات حتى تقوم بإزالتها باستخدام FileUploading.delete(). تبقى الملفات في التخزين حتى إذا تم حذف الكيان المرتبط، لذا قم بتنظيفها بشكل صريح.

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

ليس مباشرة عبر هذه SDK. تتبع قيم filename التي تحصل عليها من upload() (مثل حفظها في قاعدة بياناتك) لإدارة الملفات لاحقًا.

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

لا — يتم الحفاظ على نسبة العرض إلى الارتفاع دائمًا. width/height تحدد صندوقًا محيطًا يتم ملاءمة الصورة داخله، مما يمنع التشويه.

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

  • تحقق من نوع الملف وحجمه قبل استدعاء upload().
  • مرر entity / id بحيث يتم تنظيم الملفات حسب الكيان في التخزين.
  • قم بتمكين compress للصور على الويب.
  • احفظ filename المعاد حتى تتمكن من delete() الملف لاحقًا.
  • قم بتنظيف الملفات غير المستخدمة بشكل صريح — فهي تبقى بعد حذف الكيان.
  • تعامل مع أخطاء التحميل باستخدام try/catch وتحقق من شكل إرجاع IError.

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