رفع الملفات Upload

مدفوع بعنصر <input type="file"> أصلي + منطقة سحب وإفلات. وعلى المستخدم توفير الطلب عبر خاصية request (فالمكتبة بلا اعتمادات تشغيل، ولا تتضمن عميل HTTP).

الاستخدام الأساسي

الاستخدام الأساسي

اختيار ملف

<script setup lang="ts">
</script>

<template>
  <LhUpload :max-size="1048576" :accept="['.png', '.jpg']" />
</template>

<script>
export default {}
</script>

<template>
  <LhUpload :max-size="1048576" :accept="['.png', '.jpg']" />
</template>

يدعم accept أيضًا صيغة سلسلة نصية مفصولة بفواصل (مثل accept=".png,.jpg"، وتُكتب كخاصية ساكنة مباشرة).

السحب والطلب المخصص

الرفع بالسحب

اسحب الملفات إلى هنا، أو انقر للرفع

<script setup>
const fakeRequest = ({ file, onProgress }) =>
  new Promise((resolve) => {
    let percent = 0
    const timer = setInterval(() => {
      percent += 20
      onProgress(percent)
      if (percent >= 100) {
        clearInterval(timer)
        resolve({ url: `https://example.com/${file.name}` })
      }
    }, 200)
  })
</script>

<template>
  <!-- الرفع بالسحب -->
  <LhUpload drag :multiple="true" :request="fakeRequest" />
</template>

<script>
export default {
  methods: {
    fakeRequest({ file, onProgress }) {
      return new Promise((resolve) => {
        let percent = 0
        const timer = setInterval(() => {
          percent += 20
          onProgress(percent)
          if (percent >= 100) {
            clearInterval(timer)
            resolve({ url: `https://example.com/${file.name}` })
          }
        }, 200)
      })
    },
  },
}
</script>

<template>
  <!-- الرفع بالسحب -->
  <LhUpload drag :multiple="true" :request="fakeRequest" />
</template>

التعطيل والحد الأقصى للعدد

يعطّل disabled الرفع؛ ويحدّد max-count أقصى عدد للملفات المرفوعة.

تعطيل / الحد الأقصى للعدد

اختيار ملف

اختيار ملف

<script setup lang="ts">
</script>

<template>
  <LhUpload disabled />
  <LhUpload :max-count="2" />
</template>

<script>
export default {}
</script>

<template>
  <LhUpload disabled />
  <LhUpload :max-count="2" />
</template>

API

LhUpload Props

اسم الخاصية	الوصف	النوع	القيمة الافتراضية
multiple	السماح بالتحديد المتعدد	boolean	false
drag	منطقة الرفع بالسحب	boolean	false
disabled	التعطيل	boolean	false
accept	الامتدادات / أنواع MIME المسموح بها، كمصفوفة (['.png', 'image/*']) أو كسلسلة مفصولة بفواصل ('.png,.jpg')	string | string[]	() => []
maxSize	الحد الأقصى لحجم الملف الواحد (بايت)	number	[LH_UPLOAD_MAX_SIZE](#const-LH_UPLOAD_MAX_SIZE)
maxCount	الحد الأقصى للعدد (0 يعني بلا حد)	number	0
request	دالة طلب الرفع (عند عدم تمريرها يقتصر العمل على التحديد المحلي والتحقق)	(options: { file: File; onProgress: (percent: number) => void; }) => Promise<{ url?: string; }>	—
sx	خصائص التخطيط السريع sx	LhSxProps	—

Events

اسم الحدث	الوصف	وسائط الاستدعاء
change	يُطلَق عند تغيُّر قائمة الملفات (إضافة ملف، انتهاء الرفع، إزالة ملف)	(files: LhUploadFile[])
success	يُطلَق بعد نجاح رفع ملف واحد	(file: LhUploadFile)
error	يُطلَق بعد فشل رفع ملف واحد	(file: LhUploadFile, reason: string)
remove	يُطلَق بعد إزالة ملف	(uid: string)

الفتحات: default (محتوى منطقة التشغيل).

LhUploadRequest

(options: { file: File; onProgress: (percent: number) => void }) => Promise<{ url?: string }>

إتاحة الوصول

• عنصر <input type="file"> الأصلي مخفي بصريًا لكنه باقٍ في شجرة إتاحة الوصول، ومُسمَّى عبر aria-label
• منطقة التشغيل role="button" + tabindex، ويُفتح منتقي الملفات بـ Enter/Space، وتُزال من التفاعل عند التعطيل
• شريط التقدّم role="progressbar" + aria-valuenow/min/max؛ ويُعلَن فشل التحقق عبر role="alert"؛ وكل زر إزالة عنصر يُسمَّى باسم الملف

تعريفات الأنواع

بنية الأنواع التي يُصدِّرها هذا المكوّن بلغة TypeScript كالتالي (مستخرجة آليًا من packages/components/upload/src/types.ts و@lh-ui/share/core/*؛ انقر كل عنصر لعرض التعريف الكامل؛ لأوصاف الخصائص انظر جدول Props أعلاه):

LhUploadProps

export interface LhUploadProps {
  /** السماح بالتحديد المتعدد */
  multiple?: boolean
  /** منطقة الرفع بالسحب */
  drag?: boolean
  /** تعطيل */
  disabled?: boolean
  /** الامتدادات / أنواع MIME المسموح بها: مصفوفة `['.png', 'image/*']` أو سلسلة مفصولة بفواصل `'.png,.jpg'` */
  accept?: string[] | string
  /** الحد الأقصى لحجم الملف الواحد (بايت) */
  maxSize?: number
  /** الحد الأقصى للعدد (0 يعني بلا حد) */
  maxCount?: number
  /** دالة طلب الرفع (عند عدم تمريرها يقتصر العمل على التحديد المحلي والتحقق) */
  request?: LhUploadRequest
  /** خصائص التخطيط السريع sx */
  sx?: LhSxProps
}

LhUploadRequest _{(من @lh-ui/share/core/upload)}

/** توقيع دالة طلب الرفع (يوفّرها المستخدم، والمكتبة لا تتضمن عميل HTTP) */
export type LhUploadRequest = (options: {
  file: File
  onProgress: (percent: number) => void
}) => Promise<{ url?: string }>

LhUploadFileStatus _{(من @lh-ui/share/core/upload)}

/** حالة عنصر الملف */
export type LhUploadFileStatus = 'ready' | 'uploading' | 'success' | 'fail'

LhUploadFile _{(من @lh-ui/share/core/upload)}

/** عنصر الملف المرفوع */
export interface LhUploadFile {
  /** معرِّف فريد (يُولَّد داخليًا أو يُقدِّمه المستخدم) */
  uid: string
  /** اسم الملف */
  name: string
  /** الحجم بالبايت */
  size: number
  /** الحالة */
  status: LhUploadFileStatus
  /** تقدّم الرفع 0-100 */
  percent: number
  /** العنوان المُعاد من الخادم (عند النجاح) */
  url?: string
  /** سبب الفشل */
  error?: string
  /** كائن File الأصلي */
  raw?: File
}

الثوابت

الثوابت العمومية التي يستخدمها هذا المكوّن كالتالي (يمكنك النقر على العنصر الذي يحمل الاسم نفسه في عمودي «النوع / القيمة الافتراضية» في جدول Props للانتقال إلى هنا):

LH_UPLOAD_MAX_SIZE _{(من @lh-ui/share/core/upload)}

/** الحد الأقصى الافتراضي للحجم 5MB */
export const LH_UPLOAD_MAX_SIZE = 5 * 1024 * 1024