پیشرفت (Progress)

نمایش میزان پیشرفت انجام یک کار، معمولاً به صورت نوار پیشرفت.

نصب (Installation)

npx @quark-lab/rad-ui add progress

نمونه‌ها (Examples)

استفاده پایه (Basic)

یک نوار پیشرفت ساده با مقدار مشخص.

مشاهده کد
1import { Progress } from "@/components/ui/progress";
2
3export default function BasicProgress() {
4  return <Progress value={33} />;
5}

با برچسب (Label)

استفاده از کامپوننت Field برای افزودن برچسب و نمایش درصد.

۶۶٪
مشاهده کد
1import { Field, FieldLabel } from "@/components/ui/field";
2import { Progress } from "@/components/ui/progress";
3
4export default function LabelProgress() {
5  return (
6    <Field>
7      <div className="flex items-center justify-between">
8        <FieldLabel>پیشرفت آپلود</FieldLabel>
9        <span className="text-sm text-muted-foreground">۶۶٪</span>
10      </div>
11      <Progress value={66} className="mt-2" />
12    </Field>
13  );
14}

کنترل‌شده (Controlled)

نوار پیشرفتی که با اسلایدر کنترل می‌شود.

مشاهده کد
1"use client";
2
3import * as React from "react";
4import { Progress } from "@/components/ui/progress";
5import { Slider } from "@/components/ui/slider";
6
7export default function ControlledProgress() {
8  const [value, setValue] = React.useState(50);
9
10  return (
11    <div className="space-y-4 w-full max-w-md">
12      <Progress value={value} />
13      <Slider
14        value={[value]}
15        onValueChange={(v) => setValue(v[0] ?? 0)}
16        max={100}
17        step={1}
18      />
19    </div>
20  );
21}

مرجع API (API Reference)

Progress

کامپوننت اصلی نوار پیشرفت. مقدار value بین ۰ تا max (پیش‌فرض ۱۰۰) است.

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
valuenumber | nullnullمقدار فعلی پیشرفت (۰ تا ۱۰۰ یا مطابق max)
maxnumber100حداکثر مقدار
getValueLabel(value: number, max: number) => stringundefinedبرچسب سفارشی برای خوانندگان صفحه
classNamestring-کلاس‌های CSS سفارشی

دسترسی‌پذیری (Accessibility)

نقش progressbar (WAI-ARIA)

کامپوننت از Radix UI Progress استفاده می‌کند و الزامات نقش progressbar در WAI-ARIA 1.2 را رعایت می‌کند تا خوانندگان صفحه بتوانند وضعیت پیشرفت را اعلام کنند.

پشتیبانی از RTL

نوار پیشرفت با جهت RTL سازگار است و از کلاس‌های منطقی استفاده می‌کند.

بهترین شیوه‌ها (Best Practices)

مقدار (Value)

  • value: عدد بین ۰ تا max (پیش‌فرض ۱۰۰). برای حالت نامشخص از null استفاده کنید.
  • max: برای مقیاس‌های غیر از ۰–۱۰۰، پراپ max را تنظیم کنید.

برچسب و توضیح

برای پیشرفت آپلود یا کارهای طولانی، از Field و FieldLabel استفاده کنید و در صورت نیاز درصد را کنار نوار نمایش دهید.

نحوه استفاده (Usage)

نمونه کامل از نحوه ایمپورت و استفاده از کامپوننت Progress.

مشاهده کد
1import { Progress } from "@/components/ui/progress";
2
3export default function MyComponent() {
4  return <Progress value={60} />;
5}

مثال‌های پیشرفته (Advanced Examples)

با برچسب (Label)

نمایش برچسب و درصد کنار نوار پیشرفت.

۶۶٪
مشاهده کد
1import { Field, FieldLabel } from "@/components/ui/field";
2import { Progress } from "@/components/ui/progress";
3
4export default function LabelProgress() {
5  return (
6    <Field>
7      <div className="flex items-center justify-between">
8        <FieldLabel>پیشرفت آپلود</FieldLabel>
9        <span className="text-sm text-muted-foreground">۶۶٪</span>
10      </div>
11      <Progress value={66} className="mt-2" />
12    </Field>
13  );
14}

کنترل‌شده (Controlled)

کنترل مقدار پیشرفت با اسلایدر.

مشاهده کد
1"use client";
2
3import * as React from "react";
4import { Progress } from "@/components/ui/progress";
5import { Slider } from "@/components/ui/slider";
6
7export default function ControlledProgress() {
8  const [value, setValue] = React.useState(50);
9
10  return (
11    <div className="space-y-4 w-full max-w-md">
12      <Progress value={value} />
13      <Slider
14        value={[value]}
15        onValueChange={(v) => setValue(v[0] ?? 0)}
16        max={100}
17        step={1}
18      />
19    </div>
20  );
21}