Avatar (صورة رمزية)

يُستخدم LhAvatar لعرض الصور الرمزية للمستخدمين أو الأشياء، ويدعم ثلاث حالات: صورة وأيقونة ونص، مع العودة التلقائية إلى البديل عند فشل تحميل الصورة.

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

صورة رمزية

يتحكم fit في وضع القص (object-fit أصلي)، ويوفّر alt نصًا بديلًا.

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

<template>
  <!-- صورة رمزية -->
  <LhAvatar src="https://api.dicebear.com/9.x/notionists/svg?seed=mo" />
  <!-- قص fit + نص بديل alt -->
  <LhAvatar
    src="https://api.dicebear.com/9.x/notionists/svg?seed=f"
    fit="cover"
    alt="صورة المستخدم الرمزية"
  />
</template>

<script>
export default {}
</script>

<template>
  <!-- صورة رمزية -->
  <LhAvatar src="https://api.dicebear.com/9.x/notionists/svg?seed=mo" />
  <!-- قص fit + نص بديل alt -->
  <LhAvatar
    src="https://api.dicebear.com/9.x/notionists/svg?seed=f"
    fit="cover"
    alt="صورة المستخدم الرمزية"
  />
</template>

الشكل والحجم

دائري ومربع، أربعة أحجام

صمكد

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

<template>
  <div style="display: flex; align-items: center; gap: 12px">
    <LhAvatar
      shape="square"
      size="small"
      text="صغير"
    />
    <LhAvatar
      shape="square"
      size="medium"
      text="متوسط"
    />
    <LhAvatar
      shape="square"
      size="large"
      text="كبير"
    />
    <LhAvatar
      size="large"
      text="دائري"
    />
  </div>
</template>

<script>
export default {}
</script>

<template>
  <div style="display: flex; align-items: center; gap: 12px">
    <LhAvatar
      shape="square"
      size="small"
      text="صغير"
    />
    <LhAvatar
      shape="square"
      size="medium"
      text="متوسط"
    />
    <LhAvatar
      shape="square"
      size="large"
      text="كبير"
    />
    <LhAvatar
      size="large"
      text="دائري"
    />
  </div>
</template>

البديل النصي وأيقونة الاحتياط

في غياب الصورة، يعود الترتيب إلى icon ثم text

رA

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

<template>
  <div style="display: flex; align-items: center; gap: 12px">
    <LhAvatar text="رسم الحبر" />
    <LhAvatar icon="user" />
    <LhAvatar text="Alice Chen" />
  </div>
</template>

<script>
export default {}
</script>

<template>
  <div style="display: flex; align-items: center; gap: 12px">
    <LhAvatar text="رسم الحبر" />
    <LhAvatar icon="user" />
    <LhAvatar text="Alice Chen" />
  </div>
</template>

يأخذ الصورة الرمزية النصية تلقائيًا الحرف الأول للعرض (بالنسبة للصينية أول حرف صيني، وبالنسبة للإنجليزية أول حرف لاتيني كبير).

فشل تحميل الصورة

بعد الفشل يعود إلى text ويُطلق حدث error

<template>
  <LhAvatar
    src="/broken-avatar.png"
    text="احتياطي"
    @error="onError"
  />
</template>

<script setup lang="ts">
function onError(e: Event) {
  console.log('avatar load error', e)
}
</script>

<template>
  <LhAvatar
    src="/broken-avatar.png"
    text="احتياطي"
    @error="onError"
  />
</template>

<script>
export default {
  methods: {
    onError(e) {
      console.log('avatar load error', e)
    },
  },
}
</script>

API

الخصائص

الخاصية	الوصف	النوع	الافتراضي
src	عنوان الصورة؛ عند فراغه يعود إلى الأيقونة/النص	string	—
alt	النص البديل	string	—
icon	اسم الأيقونة (أيقونات LhIcon المدمجة، تُعرض عند غياب src)	LhIconName	—
text	المحتوى النصي (عند غياب src وicon يُعرض الحرف الأول)	string	—
shape	شكل الصورة الرمزية	"circle" | "square"	'circle'
size	حجم الصورة الرمزية	"small" | "medium" | "large" | "mini" | "x-large"	'medium'
fit	وضع تحميل الصورة: fill / contain / cover	"fill" | "contain" | "cover" | "none" | "scale-down"	'cover'
sx	خصائص التخطيط السريع sx	LhSxProps	—

الأحداث

الحدث	الوصف	معاملات الاستدعاء
error	يُطلق عند فشل تحميل الصورة	(e: Event)

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

• في وضع الصورة يوفّر عنصر <img alt> نفسه النص البديل؛ وعند عدم تمرير alt يعود إلى text ثم إلى avatar
• في وضع الأيقونة/النص يتولّى العنصر الجذري role="img، ويُستخدم alt (إن وُجد) اسمًا لإمكانية الوصول؛ وتُعلَّم الأيقونة نفسها بـ aria-hidden

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

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

LhAvatarProps

export interface LhAvatarProps {
  /** عنوان الصورة؛ عند فراغه يعود بالترتيب إلى الأيقونة ثم النص */
  src?: string
  /** النص البديل عند فشل تحميل الصورة، ويُستخدم أيضًا قيمةً لـ alt */
  alt?: string
  /** اسم الأيقونة (تُعرض عندما يكون src فارغًا أو يفشل في التحميل، مأخوذ من أيقونات LhIcon المدمجة) */
  icon?: LhIconName
  /** محتوى الصورة الرمزية النصية (عند غياب src وicon يُعرض الحرف الأول) */
  text?: string
  /** شكل الصورة الرمزية */
  shape?: LhAvatarComponentShape
  /** حجم الصورة الرمزية */
  size?: LhAvatarSize
  /** وضع تحميل الصورة: fill / contain / cover */
  fit?: 'fill' | 'contain' | 'cover' | 'none' | 'scale-down'
  /** خصائص التخطيط السريع sx */
  sx?: LhSxProps
}

LhAvatarSize

export type LhAvatarSize = LhComponentSize

LhAvatarShape

export type LhAvatarShape = LhAvatarComponentShape

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

export type LhAvatarShape = 'circle' | 'square'

LhIconName _{(مأخوذ من @lh-ui/share/core/icon (svgs.ts))}

export type LhIconName = keyof typeof LH_ICON_SVGS_CONST

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

export type LhComponentSize = (typeof LH_SIZE_CONST)[keyof typeof LH_SIZE_CONST]