التثبيت
npx sdaia-ui@latest add error-summary
الاستخدام
import { ErrorSummary } from '@/components/ui/ErrorSummary';<ErrorSummary
autoFocus
title="There is a problem"
intro="Fix the following to continue:"
errors={[
{ id: "full-name", message: "Enter your full name" },
{ id: "email", message: "Enter a valid email address" },
]}
/>الاتجاه من اليمين إلى اليسار
تنعكس القائمة والنقاط والروابط للعربية.
جارٍ تحميل العرض التوضيحي: error-summary-rtl
أمثلة
خطآن
تُرك حقلان مطلوبان فارغين. كل رابط ينقل التركيز إلى حقله.
جارٍ تحميل العرض التوضيحي: error-summary-default
ثلاثة أخطاء
ثلاثة حقول تحتاج إلى تصحيح، منها قائمة اختيار.
جارٍ تحميل العرض التوضيحي: error-summary-three-items
أربعة أخطاء
أطول نسخة. فكّر في تجميع الحقول عندما تطول القائمة.
جارٍ تحميل العرض التوضيحي: error-summary-four-items
بدون مقدمة
سطر المقدمة اختياري.
جارٍ تحميل العرض التوضيحي: error-summary-without-intro
بعد إرسال فاشل
أرسل النموذج فارغًا: يظهر الملخص ويأخذ التركيز. صحّح الحقول وأرسل مرة أخرى.
جارٍ تحميل العرض التوضيحي: error-summary-on-submit
متى تستخدمه
- النماذج الطويلة ذات الحقول المتعددة
- بعد إرسال فاشل
- أخطاء الخادم التي لا يمكن عرضها بجانب حقل
- النماذج التي قد يكون فيها الخطأ خارج الشاشة
متى لا تستخدمه
- نماذج الحقل الواحد — استخدم الخطأ المضمن
- الرسائل التي لا تتعلق بالتحقق
- رسائل النجاح أو المعلومات — استخدم التنبيه
- بديلًا عن الخطأ المضمن تحت كل حقل
الخصائص
الخاصية | النوع | القيمة الافتراضية | مطلوبة |
|---|---|---|---|
title | ReactNode | — | اختيارية |
intro | ReactNode | — | اختيارية |
errors | { id?: string; href?: string; message: ReactNode }[] | — | اختيارية |
autoFocus | boolean | false | اختيارية |
headingLevel | 2 | 3 | 4 | 5 | 6 | 2 | اختيارية |
onErrorClick | (error, event) => void | — | اختيارية |
dir | "ltr" | "rtl" | inherited | اختيارية |
إمكانية الوصول
- الملخص بدور role="alert"، ويسمّيه عنوانه (aria-labelledby)، ويقبل التركيز بـ tabIndex=-1.
- انقل التركيز إليه بعد الإرسال الفاشل: اعرضه مع autoFocus، أو استدعِ ref.current.focus() إذا بقي معروضًا بين محاولات الإرسال.
- كل عنصر رابط إلى #<معرّف الحقل>. تفعيله ينقل التركيز إلى الحقل (أو أول عنصر قابل للتركيز داخله) ويُظهر تسميته، دون تغيير الرابط.
- تُعرض الأخطاء بأيقونة ونص لا باللون وحده. أبقِ الخطأ المضمن على كل حقل مع aria-invalid.
السلوك المتجاوب
- يملأ الملخص حاويته ويلف الرسائل الطويلة؛ لا عرض ثابتًا فيه.
- تستخدم المسافات والخطوط الرموز المتجاوبة.