فهرست رتبه‌دار (RankedList)

معرفی

RankedList پاسخ «چه چیزی بالاست؟» است: واژه‌های پرتکرار، هشتگ‌ها، صفحه‌ها، موجودیت‌ها، برنامه‌های یک شبکه، مضمون‌های گفتمان. هر ردیف یک چیز است با رتبه (اختیاری)، نام، عدد به‌صورت متن، یک نوار ملایم که همان عدد را تکرار می‌کند، تغییر نسبت به دورهٔ مقایسه و یک مقصد برای کل ردیف.

جای ابر رنگی کلمه و نمودار میله‌ای افقی را می‌گیرد: رنگ ابر تزئین است و اندازهٔ واژه خواندنی نیست؛ نمودار میله‌ای افقی محور و برچسب ریز دارد و نه فهرست معنایی است نه پیوند.

• یک <ol> با نام است؛ صفحه‌خوان تعداد و ترتیب را می‌گوید.
• نوار aria-hidden است و یک رنگ (--chart-1) با شدت متناسب؛ هیچ معنایی فقط به نوار یا رنگ تکیه ندارد.
• ردیف با href پیوند است (از linkComponent قاب)، با onSelect دکمه؛ هر دو کل ردیف را هدف می‌کنند و فوکوس دیدنی دارند.
• بارگذاری، خالی‌بودن و خطا از state می‌آید؛ کارت دور آن مال شماست.

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

• روند در زمان — از PartoLineChart یا PartoAreaChart استفاده کنید
• سهم چند دسته از یک کل با رنگ معنادار (احساس، موضع) — از Distribution استفاده کنید
• فهرست رکوردهای کامل با چند ستون و مرتب‌سازی — از DataTable استفاده کنید
• توزیع روی نقشهٔ ایران — از IranMap استفاده کنید

زمین بازی

import { RankedList } from '@partodata/ui/ranked-list'

<RankedList
  aria-label="واژه‌های پرتکرار"
  items={items} showRank maxItems={5}
/>

استفاده

import { RankedList } from '@partodata/ui/ranked-list'

RankedList فقط از زیرمسیر @partodata/ui/ranked-list می‌آید (در بسته‌ی اصلی نیست: state آن نمای حالت صفحه را می‌آورد).

<ChartCard>
  <ChartCardHeader title="واژه‌های پرتکرار" />
  <ChartCardContent className="p-3">
    <RankedList
      aria-label="واژه‌های پرتکرار"
      items={words.map((word) => ({
        id: word.id,
        label: word.text,
        value: word.count,
        delta: { value: word.change, comparisonLabel: 'نسبت به 7 روز قبل' },
        href: `/search?q=${encodeURIComponent(word.text)}`,
      }))}
      maxItems={8}
      onShowAll={() => router.push('/words')}
    />
  </ChartCardContent>
</ChartCard>

داخل DashboardChart height="content" حالت را به همان DashboardChart state بدهید و RankedList را بدون state بگذارید.

حالت‌ها و انواع

بارگذاری، خالی و خطا

<RankedList
  aria-label="صفحه‌های برتر"
  items={pages}
  state={pageState({ data: pages, isLoading, error, onRetry: load, emptyCopy: { title: 'هنوز صفحه‌ای ثبت نشده است' } })}
/>

فیلتری که فهرست می‌راند

<RankedList
  aria-label="هشتگ‌ها"
  size="sm"
  selectedId={hashtag}
  items={tags.map((tag) => ({
    id: tag.id,
    label: `#${tag.name}`,
    value: tag.count,
    onSelect: () => setHashtag(tag.id),
  }))}
/>

ردیف برگزیده aria-pressed می‌گیرد و علاوه بر رنگ، قاب نازک و برچسب پررنگ‌تر دارد.

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

Props

RankedList

RankedListItem

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

• فهرست ol با نام است و هر ردیف li؛ شمار و ترتیب را صفحه‌خوان می‌گوید
• هر ردیف تعاملی یک توقف Tab با حلقهٔ فوکوس دیدنی و ناحیهٔ لمس حداقل 36 (یا 28) پیکسل است
• عدد و تغییر همیشه متن‌اند؛ نوار و رنگ تنها حامل معنا نیستند (WCAG 1.4.1)
• جهت تغییر با پیکان و علامت چاپی دیده می‌شود، نه با رنگ
• ارقام ASCII چاپ می‌شوند و فونت فارسی‌شان می‌کند

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

• Distribution — سهم چند دستهٔ رنگ‌معنادار از یک کل
• HashtagPerformanceRow — ردیف عملکرد یک هشتگ با روند
• PartoWordCloud — ابر واژه‌ها برای نمایش و کشف، نه برای خواندن رتبه
• DataTable — فهرست چندستونه با مرتب‌سازی