Tour
Tour dẫn người dùng qua các phần quan trọng của sản phẩm từng bước: làm tối phần còn lại, khoét sáng đúng phần tử và giải thích bằng TeachingPopover.
steps nhận target là CSS selector hoặc ref (bỏ trống → popover giữa màn hình), title, content, placement (top / bottom / start / end — tự đảo ở RTL) và media. Popover modal: focus vào trong, Tab không thoát ra ngoài, Esc đóng, kết thúc thì trả focus về chỗ cũ. Phần tử được cuộn vào tầm nhìn và theo dõi mỗi khung hình (cuộn, đổi kích thước). Spotlight có viền outline nên vẫn thấy ở chế độ tương phản cao. useTour() điều khiển start / stop / next / back / goTo.
Yugen Labs · thử nghiệmComponent này nằm ngoài SemVer: API có thể đổi ở một bản minor, và thay đổi sẽ được ghi trong Có gì mới. Chính sách phiên bản
Import
Cài từ npm, chép mã nguồn vào dự án bằng @yugen-ui/cli hoặc shadcn CLI, hoặc import thẳng khi làm việc trong repo này.
TSX
// npm install yugen-uiimport { Tour, useTour, type TourStep } from "yugen-ui";Biến thể
Mỗi ô là một mẫu độc lập: hover để Copy, hoặc bấm Code để xem mã nguồn.
Bảng điều khiển của bạn
Một bước, controlled, brand
target là ref; open / onOpenChange điều khiển từ ngoài.
Cách dùng
Nên
- Giữ tour ngắn (3–5 bước), mỗi bước một ý.
- Luôn có Bỏ qua và cho mở lại tour từ menu Trợ giúp.
- Nhắm vào phần tử ổn định (id, data-attribute) thay vì class dễ đổi.
Không nên
- Không tự mở tour mỗi lần vào trang — chỉ lần đầu hoặc khi người dùng yêu cầu.
- Không đặt thao tác bắt buộc bên trong tour.
- Không dùng tour để bù cho giao diện khó hiểu.
Props
| Prop · Kiểu | Mặc định | Mô tả |
|---|---|---|
| steps{ target?, title, content, placement?, media? }[] | Mặc định: — | Các bước; target là selector hoặc ref. |
| open / defaultOpen / onOpenChangeboolean | Mặc định: — | Trạng thái mở. |
| step / defaultStep / onStepChangenumber | Mặc định: — | Bước hiện tại (từ 0). |
| onFinish() => void | Mặc định: — | Bấm Hoàn tất ở bước cuối. |
| appearance"normal" | "brand" | Mặc định: "normal" | Bề mặt như TeachingPopover. |
| spotlightPadding / closeOnOverlayClicknumber / boolean | Mặc định: 8 / false | Khoảng hở spotlight; bấm lớp phủ để đóng. |
| nextLabel / backLabel / skipLabel / finishLabelstring | Mặc định: — | Nhãn nút. |
| useTour | Mặc định: — | Điều khiển trong cây con của Tour. |
Messages
Chữ có sẵn của component: nhãn, aria-label, thông báo cho trình đọc màn hình.
Mặc định là tiếng Anh. Đổi qua prop messages của YugenProvider, theo namespace bên dưới; messagesVi chứa bản tiếng Việt. Xem Ngôn ngữ giao diện.
messages.tour
| Khoá · Kiểu | Mặc định (tiếng Anh) | messagesVi |
|---|---|---|
| nextstring | Mặc định (tiếng Anh)"Next" | messagesVi"Tiếp" |
| backstring | Mặc định (tiếng Anh)"Back" | messagesVi"Quay lại" |
| skipstring | Mặc định (tiếng Anh)"Skip" | messagesVi"Bỏ qua" |
| finishstring | Mặc định (tiếng Anh)"Finish" | messagesVi"Hoàn tất" |
| roleDescriptionstring aria-roledescription của bề mặt hướng dẫn. | Mặc định (tiếng Anh)"tour" | messagesVi"hướng dẫn" |
| stepstring Chữ ẩn (sr-only) trước số bước "1 / 3". | Mặc định (tiếng Anh)"Step" | messagesVi"Bước" |