ProgressBar · ProgressRing

Thanh và vòng tiến độ có kiểm soát với trạng thái không xác định.

WebReact NativeTiến độ

Thử ngay

Đang chuẩn bị ví dụ…

JavaScript đang tắt. Đoạn mã bên dưới là ví dụ đầy đủ.

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;
}

Cách dùng ngắn nhất

Upload.jsx

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

Những gì nó xử lý giúp bạn

Giá trị được giới hạn trong 0…max, và null hiển thị dải quét không xác định hoặc cung tròn quay.
Giá trị mới giữa chừng tiếp tục với vận tốc của nó.
Một đường hoặc cung liền mạch, không bao giờ là các đoạn nhảy cóc.
Lò xo có duration kết thúc đúng thời điểm đó.

Dùng cho

Tải tệp lên.
Dung lượng đã dùng trong hạn mức.
Tiến độ qua quy trình thanh toán.

Props

`ProgressBar`

Prop	Kiểu	Mặc định	Mô tả
`value`	`number \| null`		Tiến độ từ `0` đến `max`; `null` là không xác định.
`max`	`number`	`100`	Giá trị nghĩa là hoàn tất.
`color`	`string`	`'currentColor'`	Màu tô.
`trackColor`	`string`	`'#e7ece9'`	Màu rãnh.
`thickness`	`number`	`8`	Độ dày đường tính bằng pixel.
`direction`	`'ltr' \| 'rtl'`	`'ltr'`	Tô từ trái (`ltr`) hoặc từ phải (`rtl`).
`transition`	`Transition`	`spring`	Đường cong timing `{ duration, easing }` hoặc lò xo `{ tempo: 'spring', spring }`. Lò xo giữ đà khi bị ngắt.

`ProgressRing`

Prop	Kiểu	Mặc định	Mô tả
`value`	`number \| null`		Tiến độ từ `0` đến `max`; `null` là không xác định.
`max`	`number`	`100`	Giá trị nghĩa là hoàn tất.
`size`	`number`	`96`	Đường kính tính bằng pixel.
`thickness`	`number`	`8`	Độ dày vòng tính bằng pixel.
`color`	`string`	`'currentColor'`	Màu cung.
`trackColor`	`string`	`'#e7ece9'`	Màu rãnh.
`children`	`ReactNode`		Nhãn hiển thị ở giữa.
`transition`	`Transition`	`spring`	Đường cong timing `{ duration, easing }` hoặc lò xo `{ tempo: 'spring', spring }`. Lò xo giữ đà khi bị ngắt.

Các props khác được chuyển tới phần tử được render, nên className, style và trình xử lý sự kiện hoạt động như bình thường.

Web và React Native

ProgressRing nhận children làm nhãn ở giữa; ProgressBar nhận direction để tô từ bên phải.

Cùng component và props hoạt động trên React Native.