پرتوپرتو

الگوهای خطا

راهنمای نمایش خطاها در پرتو — 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>

صفحات مرتبط