صورة Image

صورة مع عنصر نائب عند فشل التحميل، مع معاينة ملء الشاشة الاختيارية (تكبير / تدوير / تبديل بين عدة صور). تستخدم loading="lazy" وdecoding="async" الأصليتين.

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

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

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

<template>
  <!-- الاستخدام الأساسي -->
  <LhImage src="https://picsum.photos/240/140" alt="صورة توضيحية" width="240" style="width: 240px" />
</template>

<script>
export default {}
</script>

<template>
  <!-- الاستخدام الأساسي -->
  <LhImage src="https://picsum.photos/240/140" alt="صورة توضيحية" width="240" style="width: 240px" />
</template>

المعاينة

المعاينة عند النقر

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

<template>
  <!-- المعاينة عند النقر -->
  <LhImage
    src="https://picsum.photos/240/140?random=2"
    alt="صورة قابلة للمعاينة"
    preview
    :preview-src-list="['https://picsum.photos/600/400?random=2', 'https://picsum.photos/600/400?random=3']"
    style="width: 240px"
  />
</template>

<script>
export default {}
</script>

<template>
  <!-- المعاينة عند النقر -->
  <LhImage
    src="https://picsum.photos/240/140?random=2"
    alt="صورة قابلة للمعاينة"
    preview
    :preview-src-list="['https://picsum.photos/600/400?random=2', 'https://picsum.photos/600/400?random=3']"
    style="width: 240px"
  />
</template>

القص والتحميل الكسول

يقابل fit خاصية object-fit الأصلية؛ ويُفعّل lazy التحميل الكسول الأصلي (لا يُحمَّل إلا عند الدخول إلى إطار العرض). ويمكن استخدام LhImageViewer بصورة مستقلة، ويستقبل images وinitial-index.

أوضاع القص fit

التحميل الكسول

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

<template>
  <!-- أوضاع القص fit -->
  <LhImage
    v-for="f in ['fill', 'contain', 'cover', 'none', 'scale-down']"
    :key="f"
    src="https://picsum.photos/240/140"
    :alt="`fit=${f}`"
    :fit="f"
    style="width: 110px; height: 80px"
  />
  <!-- التحميل الكسول -->
  <div style="max-height: 120px; overflow-y: auto; width: 100%">
    <LhImage
      v-for="i in 4"
      :key="i"
      :src="`https://picsum.photos/240/120?random=${i}`"
      :alt="`صورة كسولة التحميل ${i}`"
      lazy
      style="width: 240px; display: block; margin-bottom: 8px"
    />
  </div>
</template>

<script>
export default {}
</script>

<template>
  <!-- أوضاع القص fit -->
  <LhImage
    v-for="f in ['fill', 'contain', 'cover', 'none', 'scale-down']"
    :key="f"
    src="https://picsum.photos/240/140"
    :alt="`fit=${f}`"
    :fit="f"
    style="width: 110px; height: 80px"
  />
  <!-- التحميل الكسول -->
  <div style="max-height: 120px; overflow-y: auto; width: 100%">
    <LhImage
      v-for="i in 4"
      :key="i"
      :src="`https://picsum.photos/240/120?random=${i}`"
      :alt="`صورة كسولة التحميل ${i}`"
      lazy
      style="width: 240px; display: block; margin-bottom: 8px"
    />
  </div>
</template>

عارض مستقل

يمكن استخدام LhImageViewer بصورة مستقلة عن LhImage، إذ يُمرَّر إليه قائمة الصور عبر images، ويحدد initial-index الصورة الأولى.

عارض مستقل

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

<template>
  <!-- عارض مستقل -->
  <LhImageViewer
    :images="['https://picsum.photos/600/400?random=11', 'https://picsum.photos/600/400?random=12']"
    :initial-index="1"
  >
    <LhButton>فتح الألبوم (ابتداءً من الصورة الثانية)</LhButton>
  </LhImageViewer>
</template>

<script>
export default {}
</script>

<template>
  <!-- عارض مستقل -->
  <LhImageViewer
    :images="['https://picsum.photos/600/400?random=11', 'https://picsum.photos/600/400?random=12']"
    :initial-index="1"
  >
    <LhButton>فتح الألبوم (ابتداءً من الصورة الثانية)</LhButton>
  </LhImageViewer>
</template>

واجهة برمجة تطبيقات Image

خصائص LhImage

الخاصية	الوصف	النوع	الافتراضي
src	عنوان الصورة	string	—
alt	النص البديل (قيد إلزامي على مستوى a11y، ومطلوب في طبقة TS)	string	—
fit	وضع القص (object-fit الأصلية)	"contain" | "cover" | "fill" | "none" | "scale-down"	'cover'
preview	ما إذا كان يمكن النقر للمعاينة	boolean	false
previewSrcList	قائمة صور المعاينة (عند عدم تمريرها تُختزل إلى [src])	string[]	—
lazy	تحميل كسول أصلي (loading="lazy")	boolean	false
sx	خصائص التخطيط السريع sx	LhSxProps	—

خصائص LhImageViewer

الخاصية	الوصف	النوع	الافتراضي
images	قائمة صور المعاينة	string[]	—
initialIndex	فهرس الصورة الأولى للمعاينة	number	0
sx	خصائص التخطيط السريع sx (تُطبَّق على صورة المعاينة)	LhSxProps	—

الأحداث

الحدث	الوصف	معاملات الاستدعاء
load	يُطلق عند نجاح تحميل الصورة	(event: Event)
error	يُطلق عند فشل تحميل الصورة (يُبدَّل إلى العنصر النائب للفشل)	(event: Event)

الفتحات: error (العنصر النائب عند الفشل)، وplaceholder.

يُصدَّر LhImageViewer بشكل مستقل، ويمكن أيضًا الاستماع إلى الحدثَين close (إغلاق المعاينة، ويُطلق أيضًا عبر Esc) وswitch (تبديل الصورة، يشمل مفاتيح الأسهم).

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

• alt مطلوب في طبقة TS، لمنع الصور بلا نص بديل
• العارض role="dialog" + aria-modal="true"، مع احتجاز التركيز، وإغلاق عبر Esc، وتبديل الصور بمفاتيح الأسهم؛ وجميع أزرار الأدوات مُسمَّاة (تكبير / تصغير / تدوير / السابقة / التالية / إغلاق)
• تحترم انتقالات التدوير والتكبير prefers-reduced-motion

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

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

LhImageProps

export interface LhImageProps {
  /** عنوان الصورة */
  src: string
  /** النص البديل (قيد إلزامي على مستوى a11y، ومطلوب في طبقة TS) */
  alt: string
  /** وضع القص (object-fit الأصلية) */
  fit?: LhImageFit
  /** ما إذا كان يمكن النقر للمعاينة */
  preview?: boolean
  /** قائمة صور المعاينة (عند عدم تمريرها تُختزل إلى [src]) */
  previewSrcList?: string[]
  /** تحميل كسول أصلي (loading="lazy") */
  lazy?: boolean
  /** خصائص التخطيط السريع sx */
  sx?: LhSxProps
}

LhImageViewerProps

/** خاصيات العارض (يُصدَّر LhImageViewer بشكل مستقل) */
export interface LhImageViewerProps {
  /** قائمة صور المعاينة */
  images: string[]
  /** الفهرس الأولي */
  initialIndex?: number
  /** خصائص التخطيط السريع sx (تُطبَّق على صورة المعاينة) */
  sx?: LhSxProps
}

LhImageFit _{(مأخوذ من @lh-ui/share/core/image)}

/** وضع قص الصورة (object-fit الأصلية) */
export type LhImageFit = 'contain' | 'cover' | 'fill' | 'none' | 'scale-down'

الثوابت

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

LH_IMAGE_ZOOM_MIN _{(مأخوذ من @lh-ui/share/core/image)}

/** حدود التكبير */
export const LH_IMAGE_ZOOM_MIN = 0.25

LH_IMAGE_ZOOM_MAX _{(مأخوذ من @lh-ui/share/core/image)}

export const LH_IMAGE_ZOOM_MAX = 4

LH_IMAGE_ZOOM_STEP _{(مأخوذ من @lh-ui/share/core/image)}

export const LH_IMAGE_ZOOM_STEP = 0.25