الثيم كنز

المكوّنات

رفع الملفات

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

Figma

المعاينة

«معكوس» هو المحتوى الإنجليزي نفسه من اليمين إلى اليسار، ليفصل خطأ الاتجاه عن خطأ الترجمة.

التثبيت

قريبًايُفتح التثبيت من السجل قريبًا، وهذه هي الأوامر التي ستشغّلها حينها.

npx ritla add file-upload

ويعمل أيضًا مع shadcn: npx shadcn@latest add @ritla/file-upload

الاعتماديات التي يضيفها: @base-ui/react, @phosphor-icons/react

التثبيت اليدوي ينسخ مصدر المكوّن إلى مشروعك. المصدر يأتي مع ترخيص Ritla UI، وأداة سطر الأوامر هي الطريق الأقصر إلى الملفات نفسها.

الاستخدام

import { FileUpload, FileUploadItem, FileUploadList } from "@/components/ui/file-upload";

<FileUpload
  label="Receipts"
  accept=".pdf,.jpg"
  maxSize={10_000_000}
  helperText="PDF or JPG, up to 10 MB each"
  onFilesAdd={(accepted, rejected) => startUploads(accepted, rejected)}
>
  <FileUploadList>
    {files.map((file) => (
      <FileUploadItem
        key={file.id}
        name={file.name}
        size={file.size}
        status={file.status}
        progress={file.progress}
        onCancel={() => cancel(file.id)}
        onRemove={() => remove(file.id)}
      />
    ))}
  </FileUploadList>
</FileUpload>

أمثلة

حالات السطر

أثناء الرفع زر X يلغي (status="uploading"، وprogress من 0 إلى 100، أو null حين لا يُعرف). بعد الاكتمال سلة المهملات تزيل والشريط ممتلئ. عند الفشل يظهر السبب تحت الاسم مع «إعادة المحاولة» (onRetry). disabled يخفت المنطقة والأسطر.

احصل على الكود ›

ملف واحد، والكاميرا على الجوال

multiple={false} يأخذ ملفًا واحدًا، وcapture="environment" يفتح الكاميرا الخلفية على الجوال حيث لا سحب ولا إفلات. اسم الملف يبقى كما سمّاه صاحبه، بأي لغة كان.

احصل على الكود ›

مرجع الخصائص

FileUpload

الخاصية	النوع	الافتراضي	الوصف
`label`	`ReactNode`	لا يوجد	التسمية فوق منطقة الإفلات، باسم المستند المطلوب («الإيصالات»).
`required`	`boolean`	`false`	النجمة بعد التسمية.
`helperText`	`ReactNode`	لا يوجد	تحت المنطقة: الأنواع والحجم والعدد المسموح، قبل أن يحاول أحد.
`error`	`ReactNode`	لا يوجد	خطأ للرفع كله («أضف إيصالًا واحدًا على الأقل»)، يحل محل النص المساعد بالأحمر.
`accept`	`string`	لا يوجد	الأنواع المسموحة كما في `<input accept>`: ‏`.pdf,.jpg` أو `image/*`. يُفحص كل ملف، مُفلتًا أو مختارًا.
`maxSize`	`number`	لا يوجد	أكبر حجم للملف بالبايت.
`maxFiles`	`number`	لا يوجد	أكبر عدد للملفات في القائمة (الأسطر الفاشلة لا تُحسب).
`multiple`	`boolean`	`true`	أكثر من ملف في المرة الواحدة.
`capture`	`"environment" \| "user"`	لا يوجد	يفتح الكاميرا على الجوال بدل منتقي الملفات.
`disabled`	`boolean`	`false`	State = Disabled.
`name`	`string`	لا يوجد	اسم حقل الملف لنموذج يرسل الملفات بنفسه.
`onFilesAdd`	`(accepted: File[], rejected: FileRejection[]) => void`	لا يوجد	الملفات المختارة أو المُفلتة بعد فحصها: ابدأ رفع `accepted` واعرض كل مرفوض في سطر بسببه (`type` أو `size` أو `count`). المكوّن لا يرفع شيئًا بنفسه.
`dropText`	`ReactNode`	لا يوجد	سطر المنطقة. الافتراضي «اسحب الملفات وأفلتها هنا أو انقر لاختيارها.» بلغة الصفحة.
`browseLabel`	`ReactNode`	لا يوجد	نص الزر. الافتراضي «اختيار ملفات»، أو «اختيار ملف» لملف واحد.

FileUploadItem

الخاصية	النوع	الافتراضي	الوصف
`name`	`string`	لا يوجد	اسم الملف كما سمّاه صاحبه، لا يُترجم ولا يُنقل حرفيًا.
`size`	`number`	لا يوجد	الحجم بالبايت، يُعرض بلغة الصفحة وأرقامها.
`status`	`"uploading" \| "done" \| "error"`	`"uploading"`	يحدد زر السطر: X يلغي أثناء الرفع، وسلة المهملات تزيل بعده.
`progress`	`number \| null`	`null`	التقدّم من 0 إلى 100 أثناء الرفع؛ `null` للشريط المخطط حين لا يُعرف.
`error`	`ReactNode`	لا يوجد	سبب الفشل بكلمات واضحة («الحجم أكبر من 10 ميغابايت»).
`onCancel / onRemove`	`() => void`	لا يوجد	زر السطر. بعد الإزالة ينتقل التركيز إلى زر السطر التالي، أو السابق، أو زر «اختيار ملفات».
`onRetry`	`() => void`	لا يوجد	يعرض «إعادة المحاولة» في السطر الفاشل.
`disabled`	`boolean`	`false`	State = Disabled.
`showFileSize / showIcon`	`boolean`	`true`	خاصيتا Show file size وShow icon.

إمكانية الوصول

لوحة المفاتيح

المفاتيح مكتوبة للاتجاه من اليسار إلى اليمين. في الاتجاه من اليمين يتبادل السهمان دورهما: السهم المتجه مع اتجاه القراءة ينقلك إلى الأمام.

المفتاح	ما يفعله
`Tab`	إلى زر «اختيار ملفات»، ثم إلى زر كل سطر.
`Enter`	على زر «اختيار ملفات» يفتح نافذة الملفات؛ على زر السطر يلغي أو يزيل.
`Space`	مثل Enter.

ARIA

منطقة الإفلات اختصار فقط: زر «اختيار ملفات» زر حقيقي يفتح حقل ملف أصليًا، فيعمل كل شيء بلوحة المفاتيح وقارئ الشاشة وعلى الجوال.
الرفع كله مجموعة باسم التسمية، وزر «اختيار ملفات» يُقرأ مع التسمية ويوصف بالنص المساعد، فيسمع قارئ الشاشة الأنواع والحدود قبل الاختيار.
زر كل سطر يحمل اسم الملف: «إلغاء رفع hotel-invoice.pdf»، «إزالة taxi-receipt.jpg».
منطقة حيّة (aria-live="polite") تعلن اكتمال الرفع أو فشله، لا كل نسبة. كل شريط تقدّم role="progressbar" باسم ملفه.

ملاحظات العربية والاتجاه

ينعكس

الأسطر: أيقونة النوع في البداية (اليمين)، ثم الاسم والحجم، والزر في النهاية (اليسار).
شريط التقدّم يمتلئ من بداية السطر، أي من اليمين.

لا ينعكس

أيقونة النوع لا تنعكس، وامتدادها يبقى لاتينيًا (PDF، JPG).
اسم الملف يبقى كما كُتب، معزولًا بـdir="auto"؛ لا يُترجم ولا يُنقل حرفيًا.
أيقونة السحابة والسلة وX لا تنعكس.

الأرقام: الحجم يتبع numerals ووحدته بلغة الصفحة: «2.3 MB» بالإنجليزية و«2.3 ميغابايت» أو «٢٫٣ ميغابايت» بالعربية.
الخط العربي: الاسم body-16 بوزن Medium والحجم body-12، بأسطر عربية أطول؛ الاسم الطويل يُقصّ بنقاط ولا يلتف.