گروه شاخص‌ها (MetricGroup)

معرفی

MetricGroup شاخص‌های یک پست، حساب یا نظر را نمایش می‌دهد و برای دادهٔ ناموجود یک قاعده دارد:

تعداد به‌شکل فشرده نمایش داده می‌شود (12.4 هزار، با ارقام لاتین که قلم آن‌ها را فارسی نمایش می‌دهد و بدون K/M لاتین) و نسبت‌ها که همیشه کسرند (0.034، یا 1.8 برای نرخ 180 درصد)، درصد (3.4٪). بازدید و پخش ویدئو دو نشانهٔ متفاوت دارند.

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

• ردیف شاخص زیر پست یا کنار ردیف فهرست (layout="inline").
• آمار سرِ صفحهٔ حساب یا نوار خلاصه (layout="stacked").

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

• برای کارت KPI داشبورد: از MetricCard استفاده کنید.
• برای جدول: عدد را در سلول جدول با همان قاعدهٔ «—» بنویسید.

استفاده

رکورد مدل را مستقیم بدهید: metrics (مثلاً post.metrics) و source. برچسب، نشانه و قالب هر شاخص از جدول سیستم طراحی می‌آید و به منبع توجه می‌کند («تماشا» در تیک‌تاک، «عضو» برای کانال تلگرام)؛ زبان فقط یک بار، در locale خود جزء، داده می‌شود. همهٔ ورودی‌ها دادهٔ ساده‌اند، پس کامپوننت سرور هم می‌تواند آن را رندر کند.

import { MetricGroup, type SocialPost } from '@partodata/ui/social'

export function PostStats({ post }: { post: SocialPost }) {
  return <MetricGroup metrics={post.metrics} source={post.source} />
}

بدون keys هر شاخصی که رکورد دارد، به ترتیب سیستم طراحی نمایش داده می‌شود (دنبال‌کننده، دنبال‌شده، پست؛ پسند، نظر، پاسخ، اشتراک، بازنشر، نقل‌قول، ذخیره، بازدید، پخش، دسترسی، مخاطب؛ نرخ تعامل؛ رتبه). رکورد تعیین می‌کند چه چیزی مربوط است: کلید حذف‌شده نمایش داده نمی‌شود و null «—» است. keys فقط وقتی لازم است که بخواهید زیرمجموعه یا ترتیب دیگری نشان دهید؛ فقط کلیدهایی پذیرفته می‌شوند که نوع رکورد دارد (ردیف پست نمی‌تواند followers بخواهد).

<MetricGroup metrics={post.metrics} source={post.source} keys={['likes', 'comments', 'views']} />

نام شاخص بیرون از MetricGroup

برای سرستون جدول، برچسب فیلتر یا ستون فایل خروجی، نام شاخص را از metricLabel بگیرید. MetricGroup هم برچسب‌هایش را از همین تابع می‌گیرد، پس یک شاخص دو نام متفاوت پیدا نمی‌کند. این تابع را از @partodata/ui/social/adapters بگیرید، نه از @partodata/ui/social: آن مسیر نشانهٔ 'use client' دارد و کامپوننت سرور نمی‌تواند تابعی از آن را فراخوانی کند؛ @partodata/ui/social/adapters در کامپوننت سرور و کلاینت هر دو کار می‌کند.

import { metricLabel, type SocialPost } from '@partodata/ui/social/adapters'

export function ViewsHeader({ post }: { post: SocialPost }) {
  return <th scope="col">{metricLabel('views', 'fa', post.source)}</th>
}

metricLabel(key, locale = 'fa', source?) یک رشته برمی‌گرداند. key یکی از کلیدهای SocialMetricKey است، locale زبان نام، و source (post.source یا یک کلید) نام وابسته به پلتفرم را انتخاب می‌کند: metricLabel('views', 'fa', 'tiktok') «تماشا» و metricLabel('followers', 'fa', { key: 'telegram' }) «عضو» است.

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

• layout="inline" (پیش‌فرض): یک خط نشانه و عدد؛ نام شاخص و عدد دقیق برای صفحه‌خوان، عدد دقیق در راهنمای شناور.
• layout="stacked": عدد بالای نام شاخص، برای سرِ صفحهٔ حساب.
• شاخصی که محصول خودش تعریف کرده (مثلاً «نظر جمع‌آوری‌شده») را در items بدهید؛ بعد از شاخص‌های سیستم طراحی می‌آید. icon نشانهٔ یکی از شاخص‌های سیستم طراحی با کلیدش ('views') یا یک عنصر نشانه است؛ بدون نشانه، نامش دیده می‌شود.
• نسبتی که صفر نیست ولی از 0.005٪ کمتر است «<0.01٪» نمایش داده می‌شود، نه «0٪».

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

Props

MetricGroupItem

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

• فهرست یک ul با role="list" صریح است (فهرست flex بدون بولت در WebKit نقشش را از دست می‌دهد) و هر شاخص یک li.
• صفحه‌خوان نام شاخص و عدد دقیق را یک بار می‌خواند؛ عدد فشرده فقط دیدنی است و با بردن نشانگر روی آن، عدد دقیق را در راهنمای شناور نشان می‌دهد. آیتم title ندارد تا نامش دوبار خوانده نشود.
• «—» پنهان است و به‌جایش «نامعلوم» خوانده می‌شود.
• ارقام در DOM لاتین‌اند؛ در en ویژگی ارقام فارسی قلم خاموش می‌شود و در ar ارقام عربی نوشته می‌شوند.

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

• MetricCard — برای یک شاخص اصلی با روند در داشبورد.
• مدل محتوای اجتماعی — قاعدهٔ Count و Ratio و مبدلی که صفرِ نامعلوم را null می‌کند.