الگوهای خطا
راهنمای نمایش خطاها در پرتو — API errors، validation، و حالتهای سیستمی
انواع خطا
| نوع | توضیح | الگو |
|---|---|---|
| خطای API | درخواست به سرور شکست خورد | ErrorState یا Alert |
| خطای validation | ورودی کاربر نامعتبر است | FormMessage زیر فیلد |
| خطای سطح صفحه | صفحه قابل نمایش نیست | error.tsx در Next.js |
| خطای شبکه | اتصال اینترنت نیست | Alert با دکمه retry |
| خطای مجوز | دسترسی غیرمجاز | صفحه 403 یا Alert |
نمونه بصری — حالت خطای API
اتصال به سرور ممکن نشد
ErrorState کامپوننت
برای خطاهایی که کل صفحه یا بخش اصلی را تحت تأثیر میگذارند:
import { ErrorState } from '@parto-system-design/ui'
<ErrorState
title="خطا در بارگذاری دادهها"
description="اطلاعات اینفلوئنسرها در حال حاضر قابل دسترسی نیست. لطفاً دوباره تلاش کنید."
action={
<Button onClick={refetch}>تلاش مجدد</Button>
}
/>Alert برای خطاهای inline
برای خطاهایی که در میان محتوا نمایش داده میشوند:
import { Alert, AlertTitle, AlertDescription } from '@parto-system-design/ui'
{error && (
<Alert variant="destructive">
<AlertCircle className="h-4 w-4" />
<AlertTitle>عملیات ناموفق بود</AlertTitle>
<AlertDescription>
{error.message || 'خطایی رخ داده است. لطفاً دوباره تلاش کنید.'}
</AlertDescription>
</Alert>
)}خطای API در داشبورد
function DashboardSection() {
const { data, error, isLoading, refetch } = useQuery(...)
if (isLoading) return <SectionSkeleton />
if (error) return (
<div className="bg-surface-100 border border-default rounded-lg p-6 flex flex-col items-center gap-4 text-center">
<AlertCircle className="h-8 w-8 text-destructive" />
<div>
<h3 className="text-foreground font-medium">خطا در بارگذاری</h3>
<p className="text-light text-sm mt-1">دادهها در دسترس نیست</p>
</div>
<Button variant="outline" size="small" onClick={refetch}>
تلاش مجدد
</Button>
</div>
)
return <DashboardContent data={data} />
}خطای شبکه
{isNetworkError && (
<Alert>
<WifiOff className="h-4 w-4" />
<AlertTitle>اتصال به اینترنت برقرار نیست</AlertTitle>
<AlertDescription>
لطفاً اتصال اینترنت خود را بررسی کنید و دوباره تلاش کنید.
</AlertDescription>
</Alert>
)}error.tsx در Next.js
برای خطاهای سطح صفحه از error.tsx استفاده کنید:
// app/(dashboard)/error.tsx
'use client'
import { ErrorState } from '@parto-system-design/ui'
import { Button } from '@parto-system-design/ui'
export default function Error({
error,
reset,
}: {
error: Error
reset: () => void
}) {
return (
<div className="flex items-center justify-center min-h-[400px]">
<ErrorState
title="مشکلی پیش آمد"
description="این بخش در حال حاضر در دسترس نیست. تیم فنی در حال بررسی است."
action={
<div className="flex gap-2">
<Button onClick={reset}>تلاش مجدد</Button>
<Button variant="outline" onClick={() => router.push('/')}>
برگشت به صفحه اصلی
</Button>
</div>
}
/>
</div>
)
}پیامهای خطا — اصول نوشتاری
| اشتباه | درست |
|---|---|
| «خطای ۵۰۰» | «سرور در حال حاضر پاسخ نمیدهد» |
| «null reference exception» | «اطلاعات یافت نشد» |
| «در صورت ادامه با پشتیبانی تماس بگیرید» | «دوباره تلاش کنید. اگر مشکل ادامه داشت، با پشتیبانی تماس بگیرید» |
| «مجاز نیست» | «برای دیدن این بخش، باید وارد حساب کاربری خود شوید» |
قوانین:
- واضح — کاربر بداند چه اتفاقی افتاده
- قابل اقدام — کاربر بداند چه کاری بکند
- بدون اصطلاح فنی — error code را در UI نمایش ندهید
- فارسی رسمی — «تلاش کنید» نه «امتحان کن»
دسترسیپذیری
// خطاها باید توسط screen reader اعلام شوند
<div role="alert" aria-live="assertive">
{error && (
<Alert variant="destructive">
<AlertDescription>{error.message}</AlertDescription>
</Alert>
)}
</div>
// برای خطاهای فرم
<div role="alert" aria-live="polite">
<FormMessage />
</div>صفحات مرتبط
- الگوهای بارگذاری — قبل از خطا، loading state را مدیریت کنید
- الگوهای فرم — نمایش خطاهای validation در فرم
- محتوا و لحن — قوانین نوشتن پیام خطا به فارسی رسمی
- دسترسیپذیری —
role="alert"،aria-live