Ratingv1.0.0
امتیاز با ستاره، عدد یا چهره، هم برای گرفتن نظر کاربر (فرم ثبت نظر) و هم برای نمایش میانگین امتیاز (کارت محصول). ستاره‌ها در RTL از راست شروع می‌شوند و مقدار با name مثل یک فیلد معمولی همراه فرم ارسال می‌شود.
این کامپوننت فعلاً برای ۱ فریم‌ورک از ۴ فریم‌ورک آماده است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
نصب
با CLI اختصاصی digdesign کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگی‌ها و فایل‌ها خودکار اضافه می‌شوند.
npx digdesign@latest add https://docs.digdesign.ir/r/rating.jsonpnpm dlx digdesign@latest add https://docs.digdesign.ir/r/rating.jsonyarn dlx digdesign@latest add https://docs.digdesign.ir/r/rating.jsonbunx --bun digdesign@latest add https://docs.digdesign.ir/r/rating.jsonاین کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
استفاده
import { Rating } from "@/components/ui/rating"
<Rating defaultValue={4} aria-label="امتیاز شما" />این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
ترکیب اجزا
Rating دو حالت دارد. در حالت عادی هر ستاره یک گزینهٔ رادیویی است و کل ستاره‌ها یک radiogroupاند. با readOnly هیچ دکمه‌ای ساخته نمی‌شود؛ ستاره‌ها یک تصویر با برچسب «۴٫۵ از ۵» می‌شوند و مقدار اعشاری به نزدیک‌ترین نیم گرد می‌شود.
ستارهٔ پر رنگ warning و ستارهٔ خالی فقط خط دور می‌گیرد؛ هیچ‌کدام شفافیت ندارند. برای ارسال با فرم name بدهید تا یک input مخفی هم‌نام مقدار را بفرستد.
دسترس‌پذیری
- کل ستاره‌ها role="radiogroup" و هر ستاره role="radio" با برچسب «۳ از ۵» است؛ برای گروه aria-label یا aria-labelledby بدهید.
- فقط ستارهٔ انتخاب‌شده در چرخهٔ Tab است. جهت‌نماها امتیاز را کم و زیاد می‌کنند؛ در RTL ArrowLeft بیشتر می‌کند، مثل جهت خود ستاره‌ها. Home و End اولین و آخرین ستاره‌اند.
- حالت readOnly یک تصویر (role="img") با برچسب کامل است، نه پنج دکمهٔ غیرفعال که صفحه‌خوان یکی‌یکی بخواند.
- رنگ تنها نشانه نیست: ستارهٔ پر، توپر است و ستارهٔ خالی فقط خط دور دارد.
مرجع API
Rating
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value | number | — | امتیاز کنترل‌شده؛ ۰ یعنی بدون امتیاز. |
| defaultValue | number | 0 | امتیاز اولیه در حالت کنترل‌نشده. |
| onValueChange | (value: number) => void | — | با هر تغییر امتیاز صدا زده می‌شود. |
| max | number | 5 | تعداد ستاره‌ها. |
| size | "sm" | "default" | "lg" | "default" | اندازهٔ ستاره‌ها. |
| readOnly | boolean | false | فقط نمایش؛ مقدار اعشاری به نزدیک‌ترین نیم گرد می‌شود و دکمه‌ای ساخته نمی‌شود. |
| disabled | boolean | false | غیرفعال با رنگ غیرفعال، بدون شفافیت. |
| clearable | boolean | false | کلیک دوباره روی همان ستاره امتیاز را صفر کند. |
| name | string | — | نام فیلد در فرم؛ یک input مخفی هم‌نام مقدار را می‌فرستد. |
| variant | "star" | "number" | "emoji" | "star" | ستاره، دکمه‌های عددی ۱ تا max، یا چهره از ناراحت تا خوشحال (emoji برای ۳ یا ۵ گزینه). |
| showLabel | boolean | false | معنای گزینهٔ زیر اشاره یا انتخاب‌شده («خوب») زیر امتیاز دیده شود. |
| getLabel | (value: number, max: number) => string | — | برچسب هر گزینه؛ پیش‌فرض «۳ از ۵»، و در emoji «خیلی بد» تا «عالی». |
این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
نمونه‌ها
کنترل‌شده با متن امتیاز
value و onValueChange مقدار را بیرون نگه می‌دارند؛ متن کنار ستاره‌ها کمک می‌کند کاربر بداند «۲» یعنی «بد».
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
عددی: ۱ تا ۵ (variant number)
همان رفتار و دسترس‌پذیری ستاره‌ها، ولی هر گزینه یک عدد است. فقط عدد انتخاب‌شده رنگ اصلی می‌گیرد؛ برای مقیاس ۱ تا ۱۰ max={10} بدهید.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
چهره: از ناراحت تا خوشحال (variant emoji)
پنج چهره از «خیلی بد» تا «عالی» (با max={3} سه چهره). چهره‌ها تا اشاره یا انتخاب خاکستری‌اند؛ انتخاب‌شده رنگی و بزرگ‌تر دیده می‌شود. showLabel معنای گزینه را زیرش می‌نویسد.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
سه چهره
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
فقط نمایش (readOnly) با نیم‌ستاره
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
اندازه‌ها
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
ده ستاره (max)
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
قابل پاک‌کردن (clearable)
کلیک دوباره روی همان ستاره امتیاز را صفر می‌کند؛ برای فرمی که امتیاز در آن اختیاری است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
در فرم ثبت نظر (name)
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
غیرفعال (Disabled)
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
کدام نمونه برای کدام موقعیت
| نمونه | کجا به کار می‌آید |
|---|---|
| کنترل‌شده با متن امتیاز | فرم نظرسنجی که کنار ستاره‌ها معنای امتیاز را هم می‌گوید |
| عددی: ۱ تا ۵ (variant number) | نظرسنجی رضایت، امتیاز به پشتیبانی یا تجربهٔ خرید |
| چهره: از ناراحت تا خوشحال (variant emoji) | بازخورد سریع بعد از تماس، سفارش یا خواندن مقاله |
| سه چهره | — |
| فقط نمایش (readOnly) با نیم‌ستاره | میانگین امتیاز در کارت یا صفحهٔ محصول |
| اندازه‌ها | — |
| ده ستاره (max) | امتیاز ۱ تا ۱۰ مثل نظرسنجی NPS |
| قابل پاک‌کردن (clearable) | کلیک دوباره روی همان ستاره امتیاز را صفر می‌کند؛ برای فرمی که امتیاز در آن اختیاری است. |
| در فرم ثبت نظر (name) | فرمی که با action یا FormData ارسال می‌شود |
| غیرفعال (Disabled) | نظر فقط بعد از تحویل سفارش ممکن است |
دستورالعمل استفاده
برای نمایش میانگین از readOnly استفاده کنید
انجام بده
میانگین امتیاز محصول قابل کلیک نیست؛ readOnly آن را یک تصویر با برچسب «۴٫۵ از ۵» می‌کند و نیم‌ستاره هم نشان می‌دهد.
انجام نده
Rating تعاملی برای میانگین کاربر را به کلیک دعوت می‌کند و مقدار اعشاری را هم نمی‌تواند نشان دهد.