ProgressBar · ProgressRing

أشرطة وحلقات تقدّم متحكَّم بها مع حالة غير محدّدة.

الويبReact Nativeالتقدّم

جرّبه

جارٍ تجهيز المثال…

JavaScript معطّل. الشيفرة أدناه هي المثال الكامل.

App.jsx

import { useEffect, useState } from 'react';
import {
  MotionNumber,
  ProgressBar,
  ProgressRing,
  motionTokens,
} from '@kkwaenggwari/animated-chorus';
import './styles.css';

export default function App({ indeterminate = false, thickness = 8, spring = 'default' }) {
  const [progress, setProgress] = useState(35);
  const [uploading, setUploading] = useState(false);
  // "default" is not a preset: undefined keeps the component's own motion.
  const transition = motionTokens.spring[spring];
  const value = indeterminate ? null : progress;

  // A pretend upload: a new value every 350 ms until it reaches 100.
  useEffect(() => {
    if (!uploading) return;
    if (progress >= 100) {
      setUploading(false);
      return;
    }
    const timer = setTimeout(() => setProgress(Math.min(100, progress + 7 + (progress % 5))), 350);
    return () => clearTimeout(timer);
  }, [uploading, progress]);

  return (
    <div className="stage">
      <div className="ring">
        <ProgressRing
          value={value}
          size={120}
          thickness={thickness}
          color="#176b52"
          trackColor="#eaf6f0"
          transition={transition}
        >
          <strong>{indeterminate ? '…' : <MotionNumber value={progress} suffix="%" />}</strong>
        </ProgressRing>
      </div>
      <ProgressBar
        className="bar"
        value={value}
        thickness={thickness}
        color="#176b52"
        trackColor="#eaf6f0"
        transition={transition}
      />
      <div className="buttons">
        <button
          className="primary"
          onClick={() => {
            setProgress(0);
            setUploading(true);
          }}
        >
          Start upload
        </button>
        <button onClick={() => setProgress(Math.min(100, progress + 10))}>+10%</button>
        <button onClick={() => setProgress(Math.max(0, progress - 25))}>−25%</button>
      </div>
    </div>
  );
}

styles.css

.stage {
  display: grid;
  justify-items: center;
  gap: 22px;
  max-width: 480px;
  margin: 0 auto;
  padding: 32px 20px;
}

.ring strong {
  font:
    800 24px system-ui,
    sans-serif;
  font-variant-numeric: tabular-nums;
  color: #0e2e24;
}

.bar {
  width: 100%;
  border-radius: 999px;
  overflow: hidden;
}

.buttons {
  display: flex;
  flex-wrap: wrap;
  justify-content: center;
  gap: 8px;
}

.buttons button {
  min-height: 44px;
  padding: 0 16px;
  border: 1px solid #cfe8dc;
  border-radius: 999px;
  background: #fff;
  font:
    600 14px system-ui,
    sans-serif;
  cursor: pointer;
}

.buttons .primary {
  border-color: #176b52;
  background: #176b52;
  color: #fff;
}

أقصر استخدام

Upload.jsx

<ProgressBar value={progress} max={100} />
<ProgressRing value={progress} size={96}>{progress}%</ProgressRing>
<ProgressBar value={null} /> {/* indeterminate */}

ما يتولّاه عنك

تُحصر القيم في 0…max، ويُظهر null مسحًا غير محدّد أو قوسًا يدور.
القيمة الجديدة في منتصف الحركة تكمل بسرعتها.
خط أو قوس متصل واحد، لا مقاطع تقفز أبدًا.
النابض مع duration ينتهي في ذلك الوقت تمامًا.

استخدمه لـ

رفع ملف.
المساحة المستخدمة من حصة.
التقدّم خلال الدفع.

Props

`ProgressBar`

Prop	النوع	الافتراضي	الوصف
`value`	`number \| null`		التقدّم من `0` إلى `max`؛ و`null` غير محدّد.
`max`	`number`	`100`	القيمة التي تعني الاكتمال.
`color`	`string`	`'currentColor'`	لون التعبئة.
`trackColor`	`string`	`'#e7ece9'`	لون المسار.
`thickness`	`number`	`8`	سماكة الخط بالبكسل.
`direction`	`'ltr' \| 'rtl'`	`'ltr'`	التعبئة من اليسار (`ltr`) أو من اليمين (`rtl`).
`transition`	`Transition`	`spring`	منحنى توقيت `{ duration, easing }` أو نابض `{ tempo: 'spring', spring }`. تحتفظ النوابض بزخمها عند المقاطعة.

`ProgressRing`

Prop	النوع	الافتراضي	الوصف
`value`	`number \| null`		التقدّم من `0` إلى `max`؛ و`null` غير محدّد.
`max`	`number`	`100`	القيمة التي تعني الاكتمال.
`size`	`number`	`96`	القطر بالبكسل.
`thickness`	`number`	`8`	سماكة الحلقة بالبكسل.
`color`	`string`	`'currentColor'`	لون القوس.
`trackColor`	`string`	`'#e7ece9'`	لون المسار.
`children`	`ReactNode`		تسمية تظهر في المنتصف.
`transition`	`Transition`	`spring`	منحنى توقيت `{ duration, easing }` أو نابض `{ tempo: 'spring', spring }`. تحتفظ النوابض بزخمها عند المقاطعة.

تذهب props الأخرى إلى العنصر المعروض، فتعمل className وstyle ومعالجات الأحداث كالمعتاد.

الويب وReact Native

يأخذ ProgressRing أبناءً لتسمية في المنتصف؛ ويأخذ ProgressBar القيمة direction ليمتلئ من اليمين.

تعمل المكوّنات نفسها وprops نفسها في React Native.