empty —— حالة فراغ

حالة الفراغ هي «حالة البيانات الصفرية» للقوائم/الجداول/نتائج البحث. نموذج حالة core/empty في غاية البساطة — قيمة منطقية واحدة hasImage، لأن قراره البصري الجوهري هو «هل مرّر المستخدم صورة أم نستخدم صورة 水墨 (رسم الحبر) الافتراضية من المكتبة»، ولكل منهما تخطيط مختلف (تحترم الصورة المخصصة المقاس الأصلي، أما الصورة الافتراضية فهي لوحة 水墨 (رسم الحبر) بعرض الصف بالكامل).

متى يُستخدم

عندما يُطبّق كل طرف LhEmpty: جدول بلا بيانات، وبحث بلا نتائج، وقائمة فُرغت، وعدم كفاية الصلاحيات غير كافية.
المشاهد المخصصة التي تحتاج إلى إعادة استخدام الشكل البصري لحالة الفراغ بنمط 水墨 (رسم الحبر).
لا يجب استخدامه: حالة التحميل. تلك مسؤولية LhSkeleton أو LhLoading؛ فحالة الفراغ تعني «تأكدنا أن البيانات صفر»، لا «لم تأتِ بعد».

طريقة الاستيراد

import { getEmptyClassNames } from '@lh-ui/share/core/empty'
import type { LhEmptyState } from '@lh-ui/share/core/empty'

نية التصميم

لا يحتوي core/empty على الحقل hasImage وحده فقط، لأن كل ما عداه (العنوان، الوصف، أزرار الإجراءات) محتوى لا حالة — يُعرَض المحتوى مباشرةً عبر الفتحات/props، ولا يحتاج إلى حساب. تمرير المحتوى عبر core أيضًا لن يزيد سوى طبقة وساطة بلا فائدة.

هذا الفصل «نحسب الحالة فقط، لا المحتوى» مبدأ عام لطبقة core في lh-ui: يجب أن يكون مدخل دوال core هو ما يُغيّر المُخرجات.

جدول الدوال

الدالة	التوقيع	القيمة المُعادة	الدور
`getEmptyClassNames`	`(state: LhEmptyState) => string[]`	مصفوفة أسماء الأصناف	التمييز بين الصورة المخصصة والصورة الافتراضية

مثال على المُخرجات:

getEmptyClassNames({ hasImage: true })   // ['lh-empty', 'lh-empty--custom-image']
getEmptyClassNames({ hasImage: false })  // ['lh-empty']

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

export interface LhEmptyState {
  hasImage: boolean
}

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

لا يُخرج core/empty حزمة سمات aria. تكمن أهمية إمكانية الوصول لحالة الفراغ في الطرف البصري:

عندما تظهر حالة الفراغ، ينبغي للقائمة/الجدول الذي يسبقها استخدام aria-live="polite" أو إخطار نشط بعد اكتمال تحميل البيانات، وإلا بقي مستخدم قارئ الشاشة على التصور القديم «القائمة بها 0 عناصر».
صورة 水墨 (رسم الحبر) الافتراضية زخرفية، فيجب أن تحمل aria-hidden="true" (يُعالَج ذلك عند العرض في الطرف البصري).
يحمل النص الوصفي المعلومة الحقيقية («لا توجد بيانات، انقر الزر للتحديث»)، ويجب أن يكون قابلًا للقراءة.
إذا كانت حالة الفراغ تتضمن زر إجراء، فالزر نفسه يستخدم دلالته الأصلية فحسب.

أمثلة الاستخدام

import { getEmptyClassNames } from '@lh-ui/share/core/empty'

getEmptyClassNames({ hasImage: false })  // ['lh-empty']

<!-- Vue3 -->
<div :class="getEmptyClassNames({ hasImage: !!image })">
  <div class="lh-empty__image">
    <slot name="image">
      <InkWash />   <!-- صورة رسم الحبر الافتراضية الاحتياطية، aria-hidden -->
    </slot>
  </div>
  <p class="lh-empty__description">{{ description }}</p>
  <div class="lh-empty__actions"><slot name="actions" /></div>
</div>

// React
const hasImage = !!image
return (
  <div className={getEmptyClassNames({ hasImage }).join(' ')}>
    <div className="lh-empty__image">{image ?? <DefaultInkWash aria-hidden="true" />}</div>
    <p className="lh-empty__description">{description}</p>
    <div className="lh-empty__actions">{actions}</div>
  </div>
)

// uniapp: صورة رسم الحبر الافتراضية هي svg، وتحتاج الأطراف غير h5 إلى استبدالها
// بمورد صوروري (يتولّاه الطرف البصري لكل جهة)

الأنماط والرموز

رسم 水墨 (رسم الحبر) الافتراضي واحد من العناصر المميزة لروح النمط الصيني في lh-ui، يُرسم بخالص CSS/SVG، وله تدرج لوني مخصص في الوضع الداكن.

ملاحظات

قرار hasImage من حق الطرف البصري: أي محتوى يمرره المستخدم عبر prop الصورة image أو فتحتها يُحسَب «صورة مخصصة».
يجب أن تظهر حالة الفراغ في موضع البيانات الأصلي (داخل جسم الجدول، داخل حاوية القائمة)، ولا تُحوَّل إلى تنبيه عام — فليست تغذية راجعة، بل حالة من حالات البيانات.
المشاهد مثل 404 / انعدام الصلاحية ليست «بيانات فارغة»، ودلالتها أقرب إلى التنبيه، فيكون LhResult (إن وُجد على الأطراف) أو تخطيط مخصص أنسب من LhEmpty.

@lh-ui/share/core/empty → getEmptyClassNames( )

返回值

（填好参数后点运行）