Timeline

کامپوننت Timeline برای نمایش توالی رویدادها استفاده می‌شود؛ مثل تاریخچه‌ی سفارش، لاگ فعالیت کاربر یا مراحل یک فرآیند. با آرایه‌ای از آیتم‌ها کار می‌کند و حالت عمودی و افقی دارد.

Import

import { Timeline } from "fara-ui";

اگر هنوز FaraUI را نصب و راه‌اندازی نکرده‌ای، ابتدا صفحه‌ی شروع به کار را ببین.

Basic Usage

<Timeline
  items={[
    { title: "سفارش ثبت شد", timestamp: "۱۴۰۴/۰۶/۱۰ - ۱۰:۳۰" },
    { title: "پرداخت تأیید شد", timestamp: "۱۴۰۴/۰۶/۱۰ - ۱۰:۳۵" },
    { title: "ارسال شد", timestamp: "۱۴۰۴/۰۶/۱۱ - ۰۹:۰۰" },
  ]}
/>

Playground

سفارش ثبت شد

۱۴۰۴/۰۶/۱۰

سفارش شما با موفقیت ثبت شد.

پرداخت تأیید شد

۱۴۰۴/۰۶/۱۰

پرداخت از طریق درگاه انجام شد.

ارسال شد

۱۴۰۴/۰۶/۱۱

بسته به پست تحویل داده شد.

orientation

description

<Timeline
  items={[
    { title: "سفارش ثبت شد", timestamp: "۱۴۰۴/۰۶/۱۰", description: "..." },
    ...
  ]}
/>

Orientation

vertical (پیش‌فرض) — رویدادها زیر هم؛ مناسب موبایل و ستون کناری
horizontal — رویدادها کنار هم؛ مناسب بالای صفحه و نمایش مراحل

Items

هر آیتم از نوع TimelineItem است:

title (الزامی) — عنوان رویداد
timestamp — زمان رویداد؛ زیر عنوان نمایش داده می‌شود
description — توضیح بیشتر؛ از نوع ReactNode است و می‌تواند JSX باشد
variant — "primary" (پیش‌فرض) یا "secondary" برای تمایز بصری نقطه‌ی رویداد

description از نوع ReactNode است و می‌تواند لینک، Badge یا چند عنصر متنی باشد:

<Timeline
  items={[
    {
      title: "سفارش ارسال شد",
      timestamp: "امروز، ۱۰:۳۰",
      variant: "primary",
      description: (
        <span>
          کد رهگیری: <a href="/tracking/ABC123">ABC123</a>
        </span>
      ),
    },
    {
      title: "پرداخت ثبت شد",
      timestamp: "امروز، ۱۰:۱۰",
      variant: "secondary",
      description: "پرداخت با موفقیت انجام شد.",
    },
  ]}
/>

Accessibility

کامپوننت با role="list" و role="listitem" پیاده شده، پس ساختار آن برای screen reader ها معنادار است.
title و timestamp متن نمایشی هستند؛ برای محتوای مهم، متن واضح و قابل فهم بنویس و زمان را با قالبی ارائه کن که کاربر بتواند آن را تشخیص دهد.
نقطه‌ها و connectorها تزئینی هستند و خودشان عنصر تعاملی یا اطلاعات مستقل برای keyboard navigation نیستند.

Data Attributes and Customize CSS

Timeline hookهای پایدار زیر را ارائه می‌کند:

Attribute	کاربرد
`data-fara-timeline`	ریشه‌ی Timeline
`data-orientation`	جهت: `vertical` یا `horizontal`
`data-fara-timeline-item`	هر رویداد
`data-fara-timeline-marker-column`	ستون marker یا ردیف marker
`data-fara-timeline-dot`	نقطه‌ی رویداد
`data-variant`	variant نقطه؛ برای مقدار صریح `primary` یا `secondary`
`data-fara-timeline-connector`	خط بین دو رویداد؛ برای آخرین آیتم وجود ندارد
`data-fara-timeline-content`	محتوای رویداد
`data-fara-timeline-title`	عنوان
`data-fara-timeline-timestamp`	زمان
`data-fara-timeline-description`	توضیح

<Timeline className="order-history" orientation="vertical" items={items} />

[data-fara-timeline][data-orientation="vertical"] {
  max-width: 520px;
}

[data-fara-timeline-dot][data-variant="secondary"] {
  background: #94a3b8;
}

[data-fara-timeline-item]:last-child [data-fara-timeline-content] {
  padding-bottom: 0;
}

[data-fara-timeline-title] {
  font-weight: 700;
}

className روی ریشه‌ی Timeline اعمال می‌شود. connector فقط بین آیتم‌ها رندر می‌شود، بنابراین آخرین آیتم connector ندارد.

Props

Prop	Type	Default	Description
`items`	`TimelineItem[]`	-	آرایه‌ی رویدادها (الزامی)
`orientation`	`"vertical" \| "horizontal"`	`"vertical"`	چیدمان تایم‌لاین
`className`	`string`	-	کلاس CSS اضافی برای سفارشی‌سازی

interface TimelineItem {
  title: string;
  description?: ReactNode;
  timestamp?: string;
  variant?: "primary" | "secondary";
}

Import​

Basic Usage​

Playground​

Orientation​

Items​

Accessibility​

Data Attributes and Customize CSS​

Props​