Progress
Mẫu chuẩnMức hoàn thành của một việc có bắt đầu và có kết thúc — không phải một chỉ báo bận vô định.
Playground
Đổi brand, theme, value, max và nhãn truy cập. Fill co theo transform, không đổi width.
Đồng bộ danh bạ: 45% (45 / 100).
import { Progress } from "@nexobox/ui";
<Progress value={45} max={100} aria-label="Đồng bộ danh bạ" />Khi nào sử dụng
Nên dùng
Báo cáo mức hoàn thành của một việc có điểm bắt đầu và điểm kết thúc đo được — tải tệp lên, hoàn tất một chuỗi bước, nạp dữ liệu có tổng số biết trước.
Khi nào không dùng
Tránh dùng
Không biết còn bao lâu hoặc còn bao nhiêu — dùng spinner của Button. Để người dùng đặt một giá trị (âm lượng, ngưỡng) — đó là Slider, Progress chỉ báo cáo, không nhận tương tác.
Anatomy
| # | Phần | Ghi chú |
|---|---|---|
| 1 | Root | <div role="progressbar">. Rộng 100%, cao cố định, bọc Track và Fill. |
| 2 | Track | Chính là nền của Root — --nf-semantic-surface-subtle, bo viên thuốc. |
| 3 | Fill | Lớp phủ trong Track, co theo scaleX(value / max) từ mép trái, màu --nf-semantic-action-primary-background. |
Variants
Biến thể duy nhất. Không có biến thể theo status kind (success, danger…) — chưa có lý do nghiệp vụ viết ra để tách màu.
States
scale = 0, Fill không hiển thị; chỉ thấy nền Track.
Fill phủ đúng tỉ lệ value / max, cạnh phải dừng giữa Track.
scale = 1, Fill phủ toàn bộ Track.
disabled, loading, error, empty, hover, focus, vô định: không có — Progress không nhận tương tác và không tự tải dữ liệu. Xem lý do trong progress.md.
Accessibility
API & triển khai
| Prop | Mặc định | Quy ước |
|---|---|---|
| value | — | Bắt buộc. Kẹp về [0, max] trước khi tính tỉ lệ. |
| max | 100 | Mốc kết thúc. max ≤ 0 render Track rỗng, không chia cho 0. |
| aria-label | — | Bắt buộc trừ khi có aria-labelledby. |
| aria-labelledby | — | Thay thế cho aria-label. |
| id, className, style | — | Truyền thẳng xuống Root, ghép chứ không ghi đè. |
Design tokens
Giá trị theo NexoCrew / light đang chọn trong playground. Track đọc --nf-semantic-surface-subtle, Fill đọc --nf-semantic-action-primary-background; transition qua --nf-component-transition-duration / -easing. Track cao/bo theo --nf-component-progress-track-height và -track-radius, hai alias có mặt trong component.tokens.json.
Do / Don't
| Nên | Tránh |
|---|---|
| Gắn aria-label mô tả việc đang đo ("Đồng bộ danh bạ") | Để Progress không có tên truy cập — trình đọc màn hình chỉ đọc "progressbar, 45%" vô nghĩa |
| Dùng khi có tổng số hoặc mốc kết thúc biết trước | Dùng khi không biết còn bao lâu — đổi sang spinner của Button |
| Cập nhật value mỗi khi có tiến triển thật | Cho value nhảy giật để "trông sống động" — Fill chỉ nên đổi khi tiến độ thật đổi |
| Dùng Progress để báo cáo một tiến độ | Gắn xử lý kéo/onChange lên Progress mong đợi hành vi như Slider |