نشان (Badge)

معرفی

کامپوننت Badge برای نمایش برچسب‌ها، شماره‌ها، وضعیت‌ها یا دسته‌بندی‌ها استفاده می‌شود.

چه زمانی استفاده نکنیم:

• برای متن طولانی‌تر از 2-3 کلمه — از TagInput یا FilterChip استفاده کنید
• برای اعمال قابل کلیک — Badge تعاملی نیست، از Button استفاده کنید
• به جای SentimentBadge برای نمایش احساسات — کامپوننت domain-specific وجود دارد
• برای ستون وضعیت یک جدول («فعال»، «سوخته · قفل») — از StatusCell استفاده کنید

استفاده

import { Badge } from '@partodata/ui'
;<div className="flex flex-wrap gap-2">
  <Badge>پیش‌فرض</Badge>
  <Badge variant="secondary">فرعی</Badge>
  <Badge variant="success">موفقیت</Badge>
  <Badge variant="warning">هشدار</Badge>
  <Badge variant="destructive">خطا</Badge>
  <Badge variant="brand">برند</Badge>
  <Badge variant="outline">حاشیه‌دار</Badge>
</div>

زمین بازی

با تغییر تنظیمات زیر، نشان را به صورت زنده مشاهده کنید.

import { Badge } from '@partodata/ui'

<Badge>
  نشان نمونه
</Badge>

انواع (Variants)

پیش‌فرض

<Badge>پیش‌فرض</Badge>

فرعی (Secondary)

<Badge variant="secondary">فرعی</Badge>

موفقیت (Success)

<Badge variant="success">موفقیت</Badge>

هشدار (Warning)

<Badge variant="warning">هشدار</Badge>

خطا (Destructive)

<Badge variant="destructive">خطا</Badge>

برند (Brand)

<Badge variant="brand">برند</Badge>

حاشیه‌دار (Outline)

<Badge variant="outline">حاشیه‌دار</Badge>

اندازه‌ها

کامپوننت Badge سه اندازه دارد: xs، sm (پیش‌فرض) و lg. نام‌های قدیمی md، tiny، small و large در 5.0 حذف شدند.

<div className="flex items-center gap-2">
  <Badge size="xs">خیلی کوچک</Badge>
  <Badge size="sm">کوچک</Badge>
  <Badge size="lg">بزرگ</Badge>
</div>

خیلی کوچک (xs)

<Badge size="xs">BETA</Badge>

مناسب برای برچسب‌های کوتاه و نشانگرهای وضعیت.

کوچک (sm) - پیش‌فرض

<Badge size="sm">جدید</Badge>
// یا
<Badge>جدید</Badge>

بزرگ (lg)

<Badge size="lg">پیشنهاد ویژه</Badge>

شدت (Emphasis)

Badge دو وزن بصری برای هر رنگ معنایی دارد: soft (پیش‌فرض — پس‌زمینهٔ کم‌رنگ 10٪) و solid (پرشدگی کامل با رنگ زنده). این محور مستقل از variant است — رنگ را variant تعیین می‌کند، شدت نمایش را emphasis.

از emphasis="solid" وقتی استفاده کنید که یک رنگ معنایی دو سطح شدت واقعی دارد که باید از هم متمایز شوند — مثلاً در warning: «نیاز به ورود مجدد» (قابل بازیابی، soft) در برابر یک هشدار جدی‌تر، یا در destructive: یک خطای موقت (soft) در برابر «مسدود دائم» (نهایی، solid). دو رتبهٔ شدت واقعی را روی یک محور رنگی یکسان نگه می‌دارد، بدون آنکه نیاز به یک variant رنگی جدید باشد.

<div className="flex flex-col gap-3">
  <div className="flex flex-wrap gap-2">
    <Badge variant="warning">نیاز به ورود مجدد</Badge>
    <Badge variant="destructive">مسدود دائم</Badge>
  </div>
  <div className="flex flex-wrap gap-2">
    <Badge variant="warning" emphasis="solid">
      نیاز به ورود مجدد
    </Badge>
    <Badge variant="destructive" emphasis="solid">
      مسدود دائم
    </Badge>
  </div>
</div>

emphasis="solid" فقط روی variantهای رنگ‌معنایی (success، warning، destructive، info، brand) اثر دارد. روی default، secondary و outline — که ساختاری‌اند نه رنگ‌معنایی — تفاوتی ایجاد نمی‌کند، چون این‌ها اصلاً مفهوم «solid» ندارند.

نقطه وضعیت (Dot)

می‌توانید یک نقطه رنگی به Badge اضافه کنید:

<div className="flex items-center gap-2">
  <Badge dot>آنلاین</Badge>
  <Badge dot variant="success">
    فعال
  </Badge>
  <Badge dot variant="warning">
    در انتظار
  </Badge>
  <Badge dot variant="destructive">
    آفلاین
  </Badge>
</div>

موقعیت نقطه

نقطه می‌تواند در انتها (پیش‌فرض) یا ابتدای Badge قرار گیرد:

<Badge dot dotPosition="start">نقطه در ابتدا</Badge>
<Badge dot dotPosition="end">نقطه در انتها</Badge>

استفاده در کنار متن

<div className="flex items-center gap-2">
  <span>وضعیت:</span>
  <Badge>فعال</Badge>
</div>

با آیکون

import { Icons } from '@partodata/ui/icons'
;<Badge>
  <Icons.check className="w-3 h-3 ms-1" />
  تایید شده
</Badge>

نمایش تعداد

<div className="relative inline-block">
  <Icons.bell className="w-6 h-6" />
  <Badge className="absolute -top-1 -end-1 px-1 min-w-[18px] h-[18px] flex items-center justify-center">5</Badge>
</div>

نمونه‌های استفاده در داشبورد

ترکیب رنگ + variant برای انتقال context دامنه‌ای (نرخ تعامل، تعداد دنبال‌کننده، احساس) بدون نیاز به کامپوننت تخصصی.

Props

دسترسی‌پذیری

• برای محتوای معنادار از تگ مناسب استفاده کنید
• برای اعداد، از aria-label توضیحی استفاده کنید
• کنتراست رنگی مناسب برای خوانایی

ملاحظات RTL

• متن به‌صورت خودکار راست‌چین می‌شود
• آیکون‌ها در سمت راست متن قرار می‌گیرند
• موقعیت‌های absolute با start/end تنظیم می‌شوند
• نقطه وضعیت بر اساس dotPosition در RTL معکوس می‌شود

راهنمای استفاده

کامپوننت‌های مرتبط

• SentimentBadge — برای نمایش احساسات مثبت/منفی/خنثی
• PlatformMark — برای نشان پلتفرم یا منبع یک مورد
• FilterChip — برای برچسب‌های قابل حذف