Component
Progress
Thanh cho biết một việc đã xong bao nhiêu khi biết được lượng: một lần tải lên, một lần nhập, các bước của một lần thiết lập. Không có value thì thanh cho thấy việc đang chạy mà không nói còn bao nhiêu. label đặt tên việc phía trên thanh, và showValue thêm phần trăm.
Xem trước
import { Progress } from "@/components/ui/progress"
<Progress label="Đang tải report.pdf" value={40} className="max-w-sm" />Cách dùng
Khi nào dùng
- Cho biết một việc đã xong bao nhiêu khi biết lượng: một lần tải lên, một lần nhập, các file của một lần đồng bộ.
- Một việc đủ lâu để người dùng phải chờ, có tên phía trên thanh.
Khi nào không dùng
- Việc không bao giờ biết lượng, như kiểm tra một giá trị. Dùng Spinner.
- Nội dung mà bạn biết bố cục trong lúc tải, như một danh sách. Dùng Skeleton.
- Các bước của một luồng mà người dùng đi qua, như một trình hướng dẫn thiết lập.
Biến thể
size
Độ dày của rãnh: md khi đứng một mình, sm trong một hàng đặc hoặc một card.
import { Progress } from "@/components/ui/progress"
<Progress label="Đang tải report.pdf" value={40} size="sm" className="max-w-sm" />
<Progress label="Đang tải report.pdf" value={40} className="max-w-sm" />Ví dụ
Tải lên
import { Progress } from "@/components/ui/progress"
<Progress label="Đang tải report.pdf" value={40} showValue />Số lượng file
max là số đếm thật, nên thanh và phần trăm theo số file đã xong.
import { Progress } from "@/components/ui/progress"
<Progress label="Đang nhập tệp" value={3} max={12} showValue />Không biết lượng
Không có value: thanh cho thấy việc đang chạy, không phải còn bao nhiêu.
import { Progress } from "@/components/ui/progress"
<Progress label="Đang chuẩn bị bản xuất của bạn" />Đặt tên ở chỗ khác
Một thanh nhỏ trong hàng card mà tên đã có trên màn hình.
import { Progress } from "@/components/ui/progress"
<Progress size="sm" aria-label="Đồng bộ lưu trữ" value={75} />Nên và không nên
Nên
- Đặt tên việc trong label, và dùng số đếm thật làm max (12 file) khi có số đó.
- Hiện phần trăm khi việc đủ lâu để người dùng phải chờ.
- Nói bằng chữ khi một việc dài đã xong hoặc thất bại; thanh một mình không được thông báo.
Không nên
- Đừng dùng khi không bao giờ biết lượng. Dùng Spinner.
- Đừng hiện một thanh cho mỗi bước của một việc; một thanh bao trọn việc.
- Đừng dùng cho các bước của một luồng mà người dùng đi qua.
Props
| Tên | Kiểu | Giá trị | Mặc định | Mô tả |
|---|---|---|---|---|
| value | number | - | - | Phần đã xong, từ 0 đến max. Bỏ qua, hoặc truyền null, khi không biết lượng: thanh indeterminate. |
| max | number | - | 100 | Giá trị khi việc xong. Dùng số đếm thật (12 file) và truyền số đã xong vào value. |
| size | enum | sm | md | md | Độ dày của rãnh: md khi đứng một mình, sm trong một hàng đặc hoặc một card. |
| label | node | - | - | Tên nhìn thấy phía trên thanh: việc đang chạy, Đang tải report.pdf. Không có label thì đặt aria-label hoặc aria-labelledby. |
| showValue | boolean | - | false | Hiện phần trăm ở cuối hàng label. Trình đọc màn hình vẫn nhận phần trăm dù có hiện hay không. |
Cấu tạo
| Phần | Mô tả |
|---|---|
| root | Rãnh: nền xám nhạt, radius-full, bằng chiều rộng của phần tử cha. Dày 4px (sm) hoặc 8px (md). |
| indicator | Phần tô accent từ đầu, dài bằng tỷ lệ việc đã xong. Không có value thì một phần ba rãnh nằm giữa (để không bị đọc thành một lượng) và nhấp. |
| wrapper | Khi có label hoặc showValue: cột giữ hàng label phía trên rãnh, gap-xs. |
| header | Hàng label: label, rồi phần trăm ở cuối, gap-sm. |
| label | Chữ primary medium 14px đặt tên việc. |
| value | Khi có showValue: chữ secondary 14px với số tabular, ở cuối hàng label. |
Khả năng truy cập
Role: progressbar
- Luôn có tên: prop label (liên kết bằng aria-labelledby), hoặc aria-label hay aria-labelledby khi tên hiện ở chỗ khác. Type bắt buộc một trong các cách đó.
- aria-valuenow, aria-valuemin và aria-valuemax theo value và max; aria-valuetext đọc phần trăm (40%). Không có value thì thanh indeterminate và không có các thuộc tính đó.
- Phần trăm nhìn thấy (showValue) bị ẩn khỏi trình đọc màn hình, vì chúng đọc aria-valuetext trên thanh.
- Phần tô chỉ dài ra khi người dùng cho phép chuyển động, và nhịp indeterminate dừng khi có prefers-reduced-motion.
- Thanh progress không phải live region. Với việc dài, cũng nói bằng chữ khi việc xong.
Cài đặt
npx werewolf-ui add progressChạy npx werewolf-ui init một lần trong app trước khi thêm component. Init cài token, thêm CSS import và luật cho agent. Add cài component này cùng các dependency và giữ nguyên theme của bạn. Xem Cài đặt để biết yêu cầu và cách cài qua registry.