نشان احساس پیشرفته (EmotionBadge)

معرفی

کامپوننت EmotionBadge برای نمایش تحلیل احساس در مقیاس پیشرفته (۹ کلاسه، الهام‌گرفته از چرخ احساسات پلاتچیک) استفاده می‌شود. مکمل SentimentBadge است، نه جایگزین آن.

ورودی emotion انعطاف‌پذیر است: می‌توانید کلید احساس، کد عددی (۱ تا ۹)، یا متن (نام انگلیسی یا برچسب محلی) بدهید — کامپوننت در هر حالت احساس درست را تشخیص می‌دهد و رنگ، آیکون و برچسب متناظر را نمایش می‌دهد.

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

• تحلیل عمیق یک پست، نظر، یا خوشه که نیازمند تفکیک احساسی دقیق است
• داشبوردهای افکارسنجی که پراکندگی احساسات را مقایسه می‌کنند
• نمایش احساس غالب در کارت جزئیات یا سطر اصلی نتیجه‌ی تحلیل

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

• در نمای خلاصه یا جدول‌های فشرده — از SentimentBadge (سه‌کلاسه) استفاده کنید
• برای توزیع درصدی چند احساس در یک جا — از EmotionDistribution استفاده کنید
• برای نمایش وضعیت عملیاتی (بحرانی/هشدار/عادی) — از StatusBadge استفاده کنید

زمین بازی

import { EmotionBadge } from '@parto-system-design/ui'

<EmotionBadge />

مقادیر و نگاشت عددی

نشان احساس روی مقیاس عددی افکارسنجی کار می‌کند. کد 0 («All») یک مقدار فیلتر کلی است و احساس واقعی نیست — کامپوننت برای آن چیزی رندر نمی‌کند. کدها از 1 (خشم) شروع و به 9 (خنثی) ختم می‌شوند:

استفاده

emotion هر یک از این فرم‌ها را می‌پذیرد:

import { EmotionBadge } from '@parto-system-design/ui';

// ۱) کلید احساس
<EmotionBadge emotion="joy" />

// ۲) کد عددی (۱ تا ۹) — مثلاً خروجی مستقیم API
<EmotionBadge emotion={4} />        {/* → شادی */}
<EmotionBadge emotion={1} count={120} />  {/* → خشم */}

// ۳) متن — نام انگلیسی، رشته‌ی عددی، یا برچسب محلی (بزرگ/کوچک مهم نیست)
<EmotionBadge emotion="Joy" />      {/* → شادی */}
<EmotionBadge emotion="شادی" />     {/* → شادی */}
<EmotionBadge emotion={'4'} />      {/* → شادی */}

// سایر تنظیمات
<EmotionBadge emotion="trust" size="sm" showLabel={false} />

// کد ۰ («All») یا مقدار ناشناخته → چیزی رندر نمی‌شود
<EmotionBadge emotion={0} />        {/* → null */}

ورودی از کد عددی (۱ تا ۹)

ورودی از متن

نام انگلیسی، رشته‌ی عددی، یا برچسب فارسی/عربی — همه به یک احساس نگاشت می‌شوند.

اندازه‌ها

Props

ابزار کمکی

برای تبدیل دستی مقدار به کلید احساس (مثلاً خارج از این کامپوننت)، از resolveEmotion استفاده کنید. خروجی برای کد ۰ و مقادیر نامعتبر null است:

import { resolveEmotion, EMOTION_VALUE_MAP, EMOTION_KEY_TO_VALUE } from '@parto-system-design/ui'

resolveEmotion(4) // 'joy'
resolveEmotion('Joy') // 'joy'
resolveEmotion('شادی') // 'joy'
resolveEmotion('4') // 'joy'
resolveEmotion(0) // null  (سنتینل «All»)
resolveEmotion(99) // null

EMOTION_VALUE_MAP[1] // 'anger'
EMOTION_KEY_TO_VALUE.neutral // 9

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

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

• هر احساس هم آیکون و هم رنگ تمایز دهنده دارد (وابستگی صرف به رنگ وجود ندارد)
• با showLabel={false} مقدار aria-label همچنان نگه داشته می‌شود
• رنگ‌ها بر اساس توکن‌های --emotion-* تنظیم شده‌اند و کنتراست WCAG AA دارند

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

• SentimentBadge — مقیاس ساده‌ی ۳ کلاسه برای نمای خلاصه
• EmotionDistribution — نمایش توزیع درصدی ۹ احساس
• FlowBadge — طبقه‌بندی گرایش مخاطب (مستقل از احساس)