Component
Slider
Chọn một số, hoặc một khoảng hai số, bằng cách kéo thumb dọc track: âm lượng, một khoảng giá, một mức zoom. Track là nền xám nhạt với đoạn accent tới thumb; phím mũi tên dịch thumb một bước.
Xem trước
import { Slider } from "@/components/ui/slider"
<div className="flex w-full max-w-xs flex-col gap-sm">
<span id="preview-slider-label" className="text-sm font-medium text-text-primary">Khối lượng</span>
<Slider aria-labelledby="preview-slider-label" defaultValue={[60]} />
</div>Cách dùng
Khi nào dùng
- Chọn một số ở chỗ cảm giác quan trọng hơn giá trị chính xác: âm lượng, zoom, độ sáng.
- Chọn một khoảng giữa hai giá trị, như một bộ lọc giá.
Khi nào không dùng
- Một số chính xác, như số lượng. Dùng Input.
- Vài lựa chọn có tên. Dùng RadioGroup, hoặc Select cho danh sách dài.
- Hiện một việc đã xong bao nhiêu. Dùng Progress.
Biến thể
orientation
horizontal lấp chiều rộng của phần tử cha. vertical lấp chiều cao của phần tử cha, ít nhất 160px.
import { Slider } from "@/components/ui/slider"
<div className="flex w-full max-w-xs flex-col gap-sm">
<span id="preview-slider-label-orientation-horizontal" className="text-sm font-medium text-text-primary">Khối lượng</span>
<Slider aria-labelledby="preview-slider-label-orientation-horizontal" defaultValue={[60]} />
</div>
<div className="flex h-40 flex-col items-center gap-sm">
<span id="preview-slider-label-orientation-vertical" className="text-sm font-medium text-text-primary">Khối lượng</span>
<Slider aria-labelledby="preview-slider-label-orientation-vertical" defaultValue={[60]} orientation="vertical" />
</div>Ví dụ
Âm lượng
import { Slider } from "@/components/ui/slider"
<div className="flex w-full max-w-xs flex-col gap-sm">
<span id="volume-label" className="text-sm font-medium text-text-primary">Khối lượng</span>
<Slider aria-labelledby="volume-label" defaultValue={[60]} />
</div>Khoảng giá
Hai giá trị tạo hai thumb, mỗi thumb một tên riêng.
import { Slider } from "@/components/ui/slider"
<Slider aria-label="Giá" thumbLabels={["Giá thấp nhất", "Giá cao nhất"]} defaultValue={[20, 80]} step={5} className="max-w-xs" />Disabled
import { Slider } from "@/components/ui/slider"
<Slider aria-label="Độ sáng" defaultValue={[30]} disabled className="max-w-xs" />Nên và không nên
Nên
- Dùng khi số chính xác ít quan trọng hơn cảm giác: âm lượng, zoom, một khoảng giá tương đối.
- Hiện giá trị cạnh slider, và để người dùng gõ số chính xác trong Input khi cần.
- Lưu trong onValueCommit, không trong onValueChange, để một cú kéo không gửi request mỗi bước.
Không nên
- Đừng dùng cho một số chính xác như số lượng; dùng Input.
- Đừng dùng cho vài lựa chọn có tên; dùng RadioGroup hoặc Select.
- Đừng dùng để hiện tiến độ; dùng Progress.
Props
| Tên | Kiểu | Giá trị | Mặc định | Mô tả |
|---|---|---|---|---|
| defaultValue | number | - | - | Mỗi thumb một số, trong một mảng: [40], hoặc [20, 80] cho một khoảng. Giá trị ở lần render đầu, khi bạn không kiểm soát nó. |
| value | number | - | - | Các giá trị dạng mảng, khi bạn kiểm soát chúng. Đi cùng onValueChange. |
| onValueChange | function | - | - | Được gọi với các giá trị mới ở mỗi bước, cả khi đang kéo. Cập nhật phần slider xem trước ở đây. |
| onValueCommit | function | - | - | Được gọi một lần khi người dùng thả hoặc bấm một phím. Lưu hoặc fetch ở đây. |
| min | number | - | 0 | Giá trị thấp nhất. |
| max | number | - | 100 | Giá trị cao nhất. |
| step | number | - | 1 | Một lần bấm phím mũi tên dịch thumb bao xa. |
| orientation | enum | horizontal | vertical | horizontal | horizontal lấp chiều rộng của phần tử cha. vertical lấp chiều cao của phần tử cha, ít nhất 160px. |
| disabled | boolean | - | false | Không focus được và không dịch được; đoạn range và các thumb chuyển sang màu disabled. |
| name | string | - | - | Tên form. Trong form, mỗi giá trị được gửi dưới tên này. |
| thumbLabels | string | - | - | string[] tùy chọn, một tên accessible cho mỗi thumb, theo thứ tự, cho một khoảng (Giá tối thiểu, Giá tối đa). Mỗi tên thay aria-label trên thumb đó. (Schema của spec không có kiểu mảng, nên prop được khai báo là string.) |
Cấu tạo
| Phần | Mô tả |
|---|---|
| root | Slider: một hàng rộng bằng phần tử cha (một cột khi vertical), cao 20px, giữ track và các thumb. |
| track | Track: 4px, radius-full, nền xám nhạt. |
| range | Range: phần tô accent từ min tới thumb, hoặc giữa hai thumb của một khoảng. |
| thumb | Một thumb: vòng tròn 16px trên nền raised, với viền control. Hover và pressed phủ overlay neutral; focus hiện ring. |
| hitArea | ::before trong suốt, căn giữa mỗi thumb, không nhỏ hơn size-target-min. |
Khả năng truy cập
Role: slider
| Phím | Hành động |
|---|---|
| ArrowRight, ArrowUp | Tăng giá trị thêm một bước. |
| ArrowLeft, ArrowDown | Giảm giá trị đi một bước. |
| PageUp, PageDown | Tăng hoặc giảm giá trị mười bước. |
| Home, End | Đặt giá trị thành min hoặc max. |
| Tab | Chuyển tới thumb kế; mỗi thumb là một tab stop riêng. |
- Mỗi thumb là một slider với aria-valuenow, aria-valuemin và aria-valuemax. Type bắt buộc aria-label hoặc aria-labelledby trên Slider, và mọi thumb nhận tên đó; đặt tên riêng cho mỗi thumb của một khoảng bằng thumbLabels (Giá tối thiểu, Giá tối đa).
- Hiện giá trị bằng chữ cạnh slider khi cần; chỉ vị trí thumb thì khó đọc chính xác.
- Thumb là 16px, nhưng vùng chạm là size-target-min (24px với chuột, 44px với cảm ứng).
- Disabled thì không trượt, và đổi range cùng thumb sang màu disabled.
Cài đặt
npx werewolf-ui add sliderChạ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.