alert —— تنبيه

التنبيه هو «تنبيه مثبَّت في الصفحة»: سبب فشل الحفظ، وقرب انتهاء الحساب، وكون النظام حاليًا في وضع القراءة فقط. وفرقه عن message هو الثبات — فالرسالة تختفي في ثوانٍ، بينما يبقى التنبيه في مكانه ليقرأه المستخدم متى شاء. وcore/alert رقيق جدًّا، وقلبه التعيين من الدلالة إلى دور المنطقة الحية.

متى يُستخدم

• عندما يُطبّق كل طرف <LhAlert>: ملخَّص التحقق من النماذج، والإعلانات على مستوى الصفحة، والتنبيهات الدائمة بنتائج العمليات، والشروحات التوجيهية.
• المحتوى الذي يحتاج إلى قراءة مستخدِم فاعلة، ولا يختفي مع الوقت.
• لا يجب استخدامه: التغذية الراجعة اللحظية للعمليات (استخدم message، فالاختفاء التلقائي أكثر تحفظًا)؛ والإشعارات غير المتزامنة على مستوى النظام (استخدم notification، فهي تلتصق بالزاوية ولا تحتل تدفق المستند)؛ والعمليات التي تحتاج إلى تأكيد المستخدم (استخدم popconfirm / dialog).

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

import {
  getAlertClassNames,
  getAlertRole,
  getAlertIconName,
} from '@lh-ui/share/core/alert'
import type { LhAlertType, LhAlertState, LhAlertRole } from '@lh-ui/share/core/alert'

نية التصميم

تعيين الدورين: warning / danger ← role="alert" (مقاطعة فورية للإعلان)، وinfo / success ← role="status" (إعلان مهذَّب في طابور). ولهذا الانقسام أساس: فتنص APG (ARIA Authoring Practices) صراحةً على أن alert للمحتوى «المهم والحساس زمنيًّا». فمستخدم يرى رسالة الخطأ بعد 5 ثوانٍ قد يكون كرَّر العملية بالفعل، بينما لا يضر تأخير رسالة النجاح ثوانٍ.

أربع حالات منطقية مستقلة في أصنافها: لكلٍّ من closable / showIcon / plain / withTitle مُعدِّل مستقل — لأنها تؤثر في التخطيط (وجود أيقونة يستلزم أن نفصل لها مكانًا، ووجود عنوان يستلزم حشوًا داخليًّا أكبر، ووجود زر إغلاق يستلزم فسحة في جانب النهاية)، لا في اللون وحده. وتقسيمها إلى أصناف مستقلة يتيح لـ SCSS كتابة التخطيط حسب التوليفات.

plain هو الوضع البسيط: يزيل لون الخلفية والحدود، ولا يبقي سوى لون الأيقونة ولون النص — للمشاهد التي «لا تريد التباهي ولكنها تحتاج إلى الثبات» (مثل سطر رمادي توضيحي في أعلى الصفحة). وفرقه عن الوضع الافتراضي هو الوزن البصري، لا الدلالة.

تعيين الأيقونات يستهلك مجموعة الأيقونات القائمة: success ← check (لا success — فليس في مجموعة الأيقونات أيقونة success، ويُعبَّر عن النجاح بعلامة الصح)، وdanger ← error. وهو طبقة تعيين من «الدلالة ← الأيقونة المحدَّدة»، فلا يحتاج طرف العرض إلى معرفة ما لدى مجموعة الأيقونات تحديدًا.

جدول الدوال

الدالة	التوقيع	القيمة المُعادة	الدور
getAlertClassNames	(state: LhAlertState) => string[]	أسماء الأصناف	النوع + 4 قيم منطقية
getAlertRole	(type: LhAlertType) => LhAlertRole	‘alert’ | ‘status’	دور المنطقة الحية
getAlertIconName	(type: LhAlertType) => string	اسم الأيقونة	أيقونات الدلالات الأربع

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

export type LhAlertType = 'info' | 'success' | 'warning' | 'danger'
export type LhAlertRole = 'alert' | 'status'

export interface LhAlertState {
  type: LhAlertType
  closable: boolean      // إظهار زر الإغلاق
  showIcon: boolean      // إظهار الأيقونة الدلالية
  plain: boolean         // الوضع البسيط (بلا خلفية أو حدود)
  withTitle: boolean     // ذو عنوان (عنوان + وصف على شكل جزأين)
}

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

getAlertRole('info')     // 'status'
getAlertRole('success')  // 'status'
getAlertRole('warning')  // 'alert'
getAlertRole('danger')   // 'alert'

• يُوضع role على عنصر الجذر للتنبيه: <div class="lh-alert lh-alert--danger" role="alert">. فالتنبيه الموجود عند تحميل الصفحة يُعلَن فورًا؛ أما التنبيه المُدرَج ديناميكيًّا فالأوثق له aria-live (فبعض برامج قراءة الشاشة تستجيب لإدراج role=alert ديناميكيًّا بشكل غير متسق).
• أيقونات بـ aria-hidden: الدلالة لم تَصل بالنص فحسب، وإعادة إعلان «تحذير» ضجيج. ولا تُكشَف الأيقونة إلا إذا حملت معلومات لا يحملها النص.
• إمكانية الوصول لزر الإغلاق: aria-label="إغلاق"، وبعد النقر يُزال التنبيه من DOM — والإزالة نفسها لا تحتاج إلى إخطار إضافي (فهي نتيجة مباشرة لعمل المستخدم).
• مستوى العنوان والوصف: عند وجود عنوان يستخدم العنوان <div class="lh-alert__title" role="heading"> (أو <h4> مباشرة)، ويبدأ الوصف سطرًا مستقلًّا. ويعالج قارئ الشاشة الأمر وفق تدفق المستند.
• لا تستخدم alert لأخطاء التحقق من النماذج: أخطاء الحقول يجب أن تلتصق بالحقل (aria-describedby + aria-invalid ضمن form)، أما alert ففيه ملخَّص لأخطاء النموذج كله.

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

import { getAlertClassNames, getAlertRole, getAlertIconName } from '@lh-ui/share/core/alert'

getAlertClassNames({ type: 'warning', closable: true, showIcon: true, plain: false, withTitle: false })
// ['lh-alert', 'lh-alert--warning', 'lh-alert--closable', 'lh-alert--show-icon']

getAlertRole('danger')     // 'alert'
getAlertIconName('success')  // 'check'

<!-- Vue3: الاستخدام الأساسي -->
<template>
  <LhAlert type="warning" :closable="true" show-icon title="تنبيه">
    النظام حاليًا ضمن نافذة الصيانة، وقد تكون بعض الميزات غير متاحة.
  </LhAlert>
</template>

<!-- ملخَّص التحقق من النموذج: لا يُرسم إلا عند عدم فراغ failedRules -->
<template>
  <LhAlert
    v-if="failedRules.length"
    type="danger"
    show-icon
    :closable="false"
    title="يحتاج النموذج إلى إصلاح N مواضع"
  >
    <ul>
      <li v-for="rule in failedRules" :key="rule.field">{{ rule.message }}</li>
    </ul>
  </LhAlert>
</template>

// React: إظهار وإخفاء مُتحكَّم به (visible state + زر الإغلاق onClick يعينه false)؛
// وبقاء محتوى التنبيه في DOM أفضل لـ SEO وللحلول البديلة، فبدِّل العرض عبر CSS display دون إلغاء التركيب

// uniapp: <view> + الأيقونات الدلالية عبر <image> أو أيقونات الخطوط؛ واستخدم catchtap لـ closable في تطبيق WeChat المصغَّر

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

اسم الصنف	الدلالة
.lh-alert	الحاوية الجذرية
.lh-alert--{info|success|warning|danger}	النوع الدلالي (لون الخلفية + الحدود + لون الأيقونة)
.lh-alert--closable	ذو زر إغلاق (فسحة في جانب النهاية)
.lh-alert--show-icon	ذو أيقونة (فسحة في جانب البداية)
.lh-alert--plain	الوضع البسيط (خلفية شفافة، بلا حدود)
.lh-alert--with-title	جزءان (حشو داخلي عمودي أكبر)
.lh-alert__icon / __title / __content / __close	الأيقونة / العنوان / الوصف / زر الإغلاق

الألوان الدلالية: --lh-info-color / --lh-success-color / --lh-warning-color / --lh-danger-color؛ ولون الخلفية الفاتح من مزج اللون الدلالي بشفافية منخفضة (مجموعة للوضع الفاتح وأخرى للداكن)؛ وانحناء الحواف --lh-border-radius-base.

ملاحظات

• التنبيه جزء من تدفق المستند: فهو يحتل مساحة في التخطيط ويدفع المحتوى. فالتنبيه الدائم في أعلى الصفحة يدفع المحتوى كله إلى الأسفل — وتثبيت الموضع (position: sticky) قرار يخص طبقة العرض، ولا يتدخل core فيه.
• طبيعة مقاطعة role="alert" سيف ذو حدَّين: وجود عدة تنبيهات danger في الصفحة في آن واحد يقطع الإعلان تباعًا، وتجربة ذلك سيئة. وفي سيناريو ملخَّص الأخطاء يُستحسن تنبيه واحد يسرد جميع المشكلات بدلًا من تنبيه لكل خطأ.
• التنبيه المُدرَج ديناميكيًّا: يتطلب role=alert أن يكون العنصر موجودًا فعلًا في DOM عند الإعلان؛ وما يُدرَج لاحقًا بـ JS يُعزَّز بـ aria-live="assertive" (للتنبيه) أو "polite" (للحالة). وهذا شأن يخص طبقة العرض.
• closable واستمرار الحالة: التنبيه الذي أغلق المستخدم سيُبعث بعد التحديث. وإن لزم «ألا يظهر مجددًا بعد الإغلاق» (مثل تحديد الإعلان كمقروء)، فعلى طبقة العمل تخزينه في localStorage.
• دلالة الوضع plain لا تتغير: البساطة تغيِّر المظهر فقط، ودور type ولون أيقونته يبقيان كما هما — فلا تحطه من danger إلى info بداعي «أن يكون أقل بروزًا»، فذلك تخفيض للدلالة.
• لا توضع أزرار تفاعلية داخل التنبيه: عند الحاجة إلى «إعادة المحاولة» أو «عرض التفاصيل» لا манع من وضع الزر في __content (دور التنبيه لا يمنع التفاعل)، ولكن لا تحاكِ صندوق حوار بـ alert.

@lh-ui/share/core/alert → getAlertRole( )

运行重置

返回值

（填好参数后点运行）