الملفات والوسائط

تخزين الملفات والوسائط من تطبيقك. كل ملف يحصل على رابط عام دائم.

تأتي الوسائط في Proyecta على مستويين. تستخدم معظم التطبيقات إمكانية رفع الوسائط المدمجة في CMS — أي رفع الصور والملفات التي يربطها الذكاء الاصطناعي تلقائياً بلوحة الإدارة والنماذج. وتحت ذلك، تتوفر Files API ذات المستوى الأدنى لمنحك تحكماً مباشراً عند الحاجة. يقوم كلاهما بالتخزين على object storage مدعوم بـ CDN ويعيدان رابطاً عاماً دائماً.

مرفقات المحادثة

يقبل حقل إدخال المحادثة الصور مباشرةً — الصق لقطة شاشة أو اسحب ملف صورة إلى حقل الإدخال. الصيغ المدعومة: PNG، JPEG، WebP، GIF، AVIF. الحجم الأقصى: 10 MB لكل صورة.

مرفقات المحادثة جزء من الرسالة وليست من مكتبة ملفاتك. للتخزين الدائم، استخدم رفع الوسائط المدمج أو Files API.

رفع الوسائط المدمج (إمكانية CMS للوسائط)

لا تتعامل معظم التطبيقات مع Files API مباشرةً — فالوسائط إمكانية مدمجة في CMS. يأتي قالب التطبيق مع hook رفع في @/hooks/useContent، ويربطهما الذكاء الاصطناعي بواجهتك. صِف ما تريد (“حقل صورة في منتجاتي”، “رفع ملف في نموذج التواصل”) وسيستخدم Proyecta الخيار المناسب:

الـ Hook	مكان الاستخدام	الـ Endpoint	الحد الأقصى للحجم
useAssetUpload()	مكتبة وسائط الإدارة — يدعم منتقي الأصول في محرر محتوى لوحة الإدارة	POST /v1/public/files	10 MB
useFormFileUpload()	ملفات النماذج العامة — ملفات يرفعها الزوار في حقل رفع ملف <FormBlock/> (إيصالات، صور)	POST /v1/public/uploads	5 MB

يعيد كلا الـ hook رابط url عاماً دائماً تخزّنه في إدخال المحتوى (الإدارة) أو إرسال النموذج (العام). بعض الأمور التي يجب معرفتها:

• كلا الحدَّين مُطبَّقان في الكود، وليسا مرتبطَين بالخطة — 10 MB للوسائط الإدارية، و5 MB لملفات النماذج العامة.
• الأنواع المقبولة هي الصور (باستثناء SVG) وملفات PDF فقط. يُرفض SVG لأسباب أمنية؛ والصور الكبيرة يتم تصغيرها تلقائياً قبل الرفع.
• لا تستدعي هذه الـ hooks مباشرةً — يقوم الذكاء الاصطناعي بتركيبها. ولا تلجأ إلى Files API أدناه إلا للتعامل ذي المستوى الأدنى أو المخصص مع الملفات.

Files API

يستطيع كل تطبيق Proyecta منشور تخزين الملفات وتقديمها. ومن صفحات تطبيقك يتم ذلك باستدعاء واحد — إذ تُدار عنك رقصة الرفع الموقَّع متعددة الخطوات:

import * as platform from '@/lib/platformClient.ts';

// Upload straight from a file input — one call, no signed-URL juggling
async function onPick(file: File) {
    const asset = await platform.assetDirectUpload({
        blob: file,
        filename: file.name,
        mimeType: file.type,
    });
    console.log(asset.url); // permanent public URL
}

// List what's stored
const { assets, hasMore } = await platform.assetList({ limit: 20 });

// Remove one
await platform.assetDelete(asset.id);

الملفات الخاصة. مرّر visibility: 'private' لتخزين ملف خارج الحاوية العامة دون رابط دائم. ثم اقرأه لاحقاً عبر رابط قصير الأجل:

const { url, expiresAt } = await platform.assetSignedUrl(asset.id, { variant: 'thumbnail' });

استخدم الوضع الخاص مع الروابط الموقَّعة لكل ما لا ينبغي تخمينه — ملفات العملاء المرفوعة، ووثائق الهوية، والتنزيلات المدفوعة.

كيف يتم رفع الملفات إلى تطبيقي؟

يتم التعامل مع رفع الملفات من خلال AI builder. اطلب من الذكاء الاصطناعي بناء سير عملية الرفع لك:

• "دع المستخدمين يرفعون صورة ملف شخصي وتخزينها في Proyecta Files"
• "أضف معرضاً للصور يمكن للمستخدمين المسجَّلين من خلاله رفع صورهم وعرضها"
• "دعني أرفق فواتير PDF بالطلبات"

يربط الذكاء الاصطناعي عملية الرفع في كود تطبيقك ويشير إلى الرابط العام المُعاد.

الأسئلة الشائعة

هل روابط الملفات عامة؟

نعم. أي ملف تعيده Files API يمتلك رابطاً عاماً دائماً. لا ترفع أي شيء لا تريد أن يكون متاحاً للعموم.

ما الحجم الأقصى للملف؟

حدود أحجام الملفات مُطبَّقة في الكود وليست مرتبطة بالخطة: 10 MB لرفع مكتبة وسائط الإدارة (useAssetUpload)، و5 MB لرفع ملفات النماذج العامة (useFormFileUpload)، و10 MB لمرفقات المحادثة. تقبل رفعات الوسائط المدمجة الصور (باستثناء SVG) وملفات PDF فقط.

هل يمكنني تغيير حجم الصور أو اقتصاصها من خلال الرابط؟

تحويلات الصور الفورية (تغيير الحجم، الاقتصاص، تحويل الصيغة) موجودة على خارطة الطريق.

قريباً

• تحويلات الصور عبر معاملات URL (تغيير الحجم، الاقتصاص، تحويل الصيغة)
• تنظيم المجلدات — إنشاء وإدارة مسارات المجلدات للملفات المخزَّنة