File Uploadv1.0.0
ناحیهٔ کشیدن‌ورهاکردن برای بارگذاری فایل، با فهرست فایل‌های انتخاب‌شده، دکمهٔ حذف هر فایل و کنترل نوع، حجم و تعداد. زیرش همان input بومی فایل است، پس کلیک، صفحه‌کلید و ارسال فرم رفتار مرورگر را دارند.
این کامپوننت فعلاً برای ۱ فریم‌ورک از ۴ فریم‌ورک آماده است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
نصب
با CLI اختصاصی digdesign کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگی‌ها و فایل‌ها خودکار اضافه می‌شوند.
npx digdesign@latest add https://docs.digdesign.ir/r/file-upload.jsonpnpm dlx digdesign@latest add https://docs.digdesign.ir/r/file-upload.jsonyarn dlx digdesign@latest add https://docs.digdesign.ir/r/file-upload.jsonbunx --bun digdesign@latest add https://docs.digdesign.ir/r/file-upload.jsonاین کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
استفاده
import { FileUpload } from "@/components/ui/file-upload"
<FileUpload name="document" accept="image/*,.pdf" />این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
ترکیب اجزا
ناحیهٔ رهاکردن یک label برای input بومی type="file" است که از دید پنهان ولی در DOM است. پس کلیک یا Enter همان پنجرهٔ انتخاب فایل سیستم‌عامل را باز می‌کند و فوکوس صفحه‌کلید روی خود ناحیه حلقهٔ فوکوس می‌گیرد.
فایل‌های رهاشده یا انتخاب‌شده با accept، maxSize و maxFiles سنجیده می‌شوند؛ ردشده‌ها با دلیل فارسی زیر ناحیه فهرست می‌شوند و onReject هم صدا زده می‌شود. فهرست فایل‌ها همیشه با input بومی هم‌گام است، پس با name فایل‌ها با submit معمولی فرم هم می‌روند.
دسترس‌پذیری
- ناحیهٔ رهاکردن label یک input فایل واقعی است؛ صفحه‌خوان آن را به‌عنوان دکمهٔ انتخاب فایل با همان متن ناحیه می‌خواند.
- کشیدن‌ورهاکردن فقط یک میان‌بر است؛ همهٔ کارها با کلیک و صفحه‌کلید هم ممکن است.
- هر فایل در فهرست یک دکمهٔ حذف با برچسب «حذف نام‌فایل» دارد و بعد از حذف فوکوس به ناحیهٔ انتخاب برمی‌گردد.
- فایل در حال بارگذاری aria-busy دارد و نوار پیشرفتش برچسب «بارگذاری نام‌فایل» می‌گیرد؛ تامنیل تصویر alt برابر نام فایل دارد.
- پیام فایل‌های ردشده در یک ناحیهٔ aria-live است و با aria-describedby به input وصل می‌شود.
مرجع API
FileUpload
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| accept | string | — | همان accept بومی؛ مثل "image/*,.pdf". |
| multiple | boolean | false | انتخاب چند فایل. |
| maxSize | number | — | بیشینهٔ حجم هر فایل به بایت. |
| maxFiles | number | — | بیشینهٔ تعداد فایل‌ها (فقط با multiple). |
| files | File[] | — | فهرست کنترل‌شدهٔ فایل‌ها. |
| onFilesChange | (files: File[]) => void | — | با هر افزودن یا حذف فایل صدا زده می‌شود. |
| onReject | (rejections: { file: File; reason: string }[]) => void | — | فایل‌های ردشده با دلیل فارسی. |
| name | string | — | نام فیلد؛ فایل‌ها با submit معمولی و FormData ارسال می‌شوند. |
| title | React.ReactNode | — | متن اصلی ناحیهٔ رهاکردن؛ پیش‌فرض «برای انتخاب کلیک کنید یا فایل را این‌جا بکشید» و هنگام کشیدن فایل «فایل را این‌جا رها کنید». |
| hint | React.ReactNode | — | خط راهنمای نوع و حجم مجاز. |
| required | boolean | — | تا وقتی فهرست خالی است ارسال فرم متوقف می‌شود. |
| invalid | boolean | false | حاشیهٔ خطا. |
| disabled | boolean | false | غیرفعال با رنگ غیرفعال. |
| removeLabel | (file: File) => string | — | برچسب دکمهٔ حذف هر فایل؛ پیش‌فرض «حذف نام‌فایل». |
| onUpload | (file, { onProgress, signal }) => Promise<void> | — | بارگذاری هر فایل پذیرفته‌شده؛ فهرست پیشرفت و درصد، بعد تیک یا خطا با «تلاش دوباره» نشان می‌دهد. حذف فایل signal را abort می‌کند. |
| layout | "list" | "grid" | "list" | ردیف با تامنیل کوچک، یا کارت با تامنیل بزرگ برای تصویر. |
این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
نمونه‌ها
در حال بارگذاری، بارگذاری‌شده و خطا (onUpload)
با onUpload هر فایل پذیرفته‌شده بلافاصله بارگذاری می‌شود و یک کارت جدا می‌گیرد: برچسب رنگی نوع فایل (PDF قرمز، اکسل سبز، ورد آبی، فشرده کهربایی) یا تامنیل تصویر، نوار پیشرفت با درصد در انتهای ردیف، بعد «بارگذاری شد» سبز یا پیام خطا با دکمهٔ متنی «تلاش دوباره» و حاشیهٔ قرمز. بالای فهرست خلاصهٔ «n فایل در حال بارگذاری…» زنده خوانده می‌شود. حین بارگذاری دکمهٔ × بارگذاری را لغو می‌کند (signal را abort می‌کند) و بعد از آن سطل فایل را حذف می‌کند. فایل صوتی دکمهٔ پخش و مکث می‌گیرد. یکی از پنج فایل نمونه عمداً وسط راه خطا می‌دهد.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
گالری تصاویر (چیدمان grid)
در چیدمان grid هر فایل یک کارت با تامنیل بزرگ، نام و وضعیت بارگذاری است و دکمهٔ حذف گوشهٔ کارت می‌نشیند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
چند فایل با سقف تعداد و حجم
files و onFilesChange فهرست را بیرون نگه می‌دارند؛ فایل چهارم یا فایل بزرگ‌تر از ۵ مگابایت با دلیل رد می‌شود.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
در فرم (name)
با name فایل‌های فهرست همراه FormData ارسال می‌شوند؛ required تا وقتی فهرست خالی است فرم را متوقف می‌کند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
متن سفارشی
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
نامعتبر (Invalid)
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
غیرفعال (Disabled)
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
کدام نمونه برای کدام موقعیت
| نمونه | کجا به کار می‌آید |
|---|---|
| در حال بارگذاری، بارگذاری‌شده و خطا (onUpload) | بارگذاری هر فایل بلافاصله بعد از انتخاب |
| گالری تصاویر (چیدمان grid) | تصاویر محصول، آلبوم یا مدارک تصویری |
| چند فایل با سقف تعداد و حجم | بارگذاری مدارک یا تصاویر محصول |
| در فرم (name) | احراز هویت یا ارسال مدارک با submit معمولی |
| متن سفارشی | — |
| نامعتبر (Invalid) | خطای اعتبارسنجی فرم از سمت سرور |
| غیرفعال (Disabled) | بارگذاری فقط بعد از تکمیل مرحلهٔ قبل |
دستورالعمل استفاده
نوع و حجم مجاز را از قبل بگویید
انجام بده
hint می‌گوید چه فایلی قبول است، تا کاربر بعد از انتخاب با خطا روبه‌رو نشود.
انجام نده
بدون راهنما، کاربر فقط بعد از انتخاب فایل اشتباه متوجه محدودیت می‌شود.