بطاقة Card

حاوية معلومات تتسع للعنوان والمحتوى والإجراءات السفلية. يمكن النقر عليها بالكامل (تحمل دلالة لوحة المفاتيح لـ button)، وتدعم حالة التحميل والتخطيط السريع sx.

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

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

مطرٌ على أوراق الموز

من خلف النافذة يُعلم الليل بالمطر، وأوراق الموز تُحدث صوتها أولًا.

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

<template>
  <LhCard title="مطرٌ على أوراق الموز">
    من خلف النافذة يُعلم الليل بالمطر، وأوراق الموز تُحدث صوتها أولًا.
  </LhCard>
</template>

<script>
export default {}
</script>

<template>
  <LhCard title="مطرٌ على أوراق الموز">
    من خلف النافذة يُعلم الليل بالمطر، وأوراق الموز تُحدث صوتها أولًا.
  </LhCard>
</template>

يتحكم shadow في توقيت عرض الظل: always (افتراضي) / hover (عند المرور بالفأرة) / never.

توقيت الظل

ظل عند المرور

يظهر الظل عند مرور الفأرة.

بلا ظل

دون ظل دائمًا.

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

<template>
  <LhCard shadow="hover" title="ظل عند المرور">يظهر الظل عند مرور الفأرة.</LhCard>
  <LhCard shadow="never" title="بلا ظل">دون ظل دائمًا.</LhCard>
</template>

<script>
export default {}
</script>

<template>
  <LhCard shadow="hover" title="ظل عند المرور">يظهر الظل عند مرور الفأرة.</LhCard>
  <LhCard shadow="never" title="بلا ظل">دون ظل دائمًا.</LhCard>
</template>

فتحة الرأس و extra

رأس مخصص

رأس مخصصإجراءات

تتيح فتحة header التحكم الكامل بمنطقة العنوان.

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

<template>
  <LhCard>
    <template #header><span>رأس مخصص</span></template>
    <template #extra>إجراءات</template>
    …
  </LhCard>
</template>

<script>
export default {}
</script>

<template>
  <LhCard>
    <template #header><span>رأس مخصص</span></template>
    <template #extra>إجراءات</template>
    …
  </LhCard>
</template>

الغلاف والتذييل

غلاف وتذييل

منطقة الغلاف

محتوى المتن……

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

<template>
  <!-- غلاف وتذييل -->
  <LhCard>
    <template #cover>…</template>
    …
    <template #footer>
      <LhButton size="small">المفضلة</LhButton>
    </template>
  </LhCard>
</template>

<script>
export default {}
</script>

<template>
  <!-- غلاف وتذييل -->
  <LhCard>
    <template #cover>…</template>
    …
    <template #footer>
      <LhButton size="small">المفضلة</LhButton>
    </template>
  </LhCard>
</template>

البطاقة بالكامل قابلة للنقر

عند clickable تتولّى البطاقة كاملةً دلالة button: يمكن التركيز عليها عبر Tab (مع حلقة تركيز :focus-visible)، ويُطلق Enter / Space حدث click.

بطاقة قابلة للنقر

انقر عليّ

البطاقة بالكامل قابلة للنقر. جمّع التركيز عليها بلوحة المفاتيح ثم اضغط Enter للتجربة.

<script setup lang="ts">
function onCardClick() {
  console.log('card clicked')
}
</script>

<template>
  <!-- بطاقة قابلة للنقر -->
  <LhCard clickable title="انقر عليّ" @click="onCardClick">…</LhCard>
</template>

<script>
export default {
  methods: {
    onCardClick() {
      console.log('card clicked')
    },
  },
}
</script>

<template>
  <!-- بطاقة قابلة للنقر -->
  <LhCard clickable title="انقر عليّ" @click="onCardClick">…</LhCard>
</template>

حالة التحميل

حالة التحميل

جارٍ التحميل

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

<template>
  <LhCard title="جارٍ التحميل" loading />
</template>

<script>
export default {}
</script>

<template>
  <LhCard title="جارٍ التحميل" loading />
</template>

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

الخصائص

الخاصية	الوصف	النوع	الافتراضي
title	عنوان البطاقة (يمكن أيضًا استخدام فتحة header)	string	—
shadow	توقيت عرض الظل	"always" | "hover" | "never"	'always'
clickable	البطاقة بالكامل قابلة للنقر (تتحمل دلالة لوحة المفاتيح لـ button)	boolean	false
loading	حالة التحميل: يُحتلّ محتوى المتن بهيكل عظمي نائب	boolean	false
themeVars	متغيرات السمة على مستوى المكوّن (تُضاف تلقائيًا بادئة --lh- إلى المفاتيح)	{ [x: string]: string; }	—
bgPattern	عنوان URL لخلفية النمط (مثل var(--lh-pattern-willow))، لا يخضع للقائمة المسموح بها العامة	string	—
sx	خصائص التخطيط السريع sx	LhSxProps	—

الأحداث

الحدث	الوصف	المعاملات
click	نقر على بطاقة قابلة للنقر (بالفأرة أو عبر Enter/Space من لوحة المفاتيح)	(e: Event) => void

متغيرات السمة

تُعرَّف القيم الافتراضية لمتغيرات CSS التالية على .lh-card، ويمكن تجاوزها عبر themeVars عموميًا أو على مستوى المكوّن:

المتغير	الوصف	الافتراضي
--lh-card-border-radius	نصف القطر	border-radius-base + 2px
--lh-card-bg	لون الخلفية	--lh-bg-color
--lh-card-border-color	لون الحد	--lh-border-color-light
--lh-card-header-padding / --lh-card-body-padding / --lh-card-footer-padding	الحشو الداخلي للأقسام الثلاثة	14px 20px / 18px 20px / 12px 20px
--lh-card-shadow / --lh-card-shadow-hover	الظل الاعتيادي / ظل المرور بالفأرة	ظل مزدوج ناعم بلون حبر دافئ
--lh-card-loading-bg / --lh-card-loading-highlight	لون قاعدة حالة التحميل / توهّج الانسياح	--lh-border-color-light / لون ممزوج يميل إلى أبيض ورق الأرز

الفتحات

الفتحة	الوصف
header	منطقة عنوان مخصصة
extra	محتوى إضافي عند طرف العنوان
cover	الغلاف
default	المحتوى الرئيسي
footer	التذييل

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

• البطاقة القابلة للنقر: role="button" + tabindex="0" + تفعيل Enter/Space (نمط APG button)
• حالة التحميل: الحاوية aria-busy="true"، والأشكال النائبة مخفية عن قارئ الشاشة
• حلقة تركيز لوحة المفاتيح عبر :focus-visible، ولا تُعرض عند النقر بالفأرة

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

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

LhCardProps

export interface LhCardProps {
  /** عنوان البطاقة (يمكن أيضًا استخدام فتحة header) */
  title?: string
  /** توقيت عرض الظل */
  shadow?: LhCardShadow
  /** البطاقة بالكامل قابلة للنقر (تتحمل دلالة لوحة المفاتيح لـ button) */
  clickable?: boolean
  /** حالة التحميل: يُحتلّ محتوى المتن بهيكل عظمي نائب */
  loading?: boolean
  /** متغيرات السمة على مستوى المكوّن (تُضاف تلقائيًا بادئة --lh- إلى المفاتيح) */
  themeVars?: Record<string, string>
  /** عنوان URL لخلفية النمط (مثل var(--lh-pattern-willow))، لا يخضع للقائمة المسموح بها العامة */
  bgPattern?: string
  /** خصائص التخطيط السريع sx */
  sx?: LhSxProps
}

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

/** توقيت عرض ظل البطاقة */
export type LhCardShadow = 'always' | 'hover' | 'never'