Yugen UI

Carousel

Carousel trình bày một chuỗi nội dung theo từng slide, điều hướng bằng nút trước / sau, chấm chỉ mục, ảnh thu nhỏ hoặc phím mũi tên.

Track dùng CSS scroll-snap nên vuốt / cuộn tự nhiên trên mọi thiết bị. loop quay vòng ở hai đầu; slidesPerView (vd. 1.15) và gap lộ một phần slide kế. Autoplay hiện tiến độ ngay trong chấm đang chọn, tự dừng khi rê chuột, focus vào slide hoặc khi tab bị ẩn, và không tự bật nếu người dùng chọn giảm chuyển động. Mỗi slide có nhãn “Slide x / n”; chấm và thumbnail là tablist điều khiển bằng mũi tên (đảo vai ở RTL), Home / End.

Fluent 2 cho web

Token, component và tài liệu luôn đồng bộ.

Bloom theo brand

Đổi data-brand là đổi màu minh hoạ.

Ngôn ngữ biểu cảm

Gradient chỉ dành cho minh hoạ và hero.

Sáng & tối

Đổi theme ngay trong khung ví dụ.

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 {  Carousel, CarouselViewport, CarouselCard, CarouselNavContainer, CarouselThumbnails, CarouselThumbnail,} 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.

Mountains at dawn

Mountains at dawn

Hills at sunset

Hills at sunset

Pine forest

Pine forest

Lake at night

Lake at night

Desert

Desert

Peek & vòng lặp

slidesPerView={1.15} lộ 15% slide kế, gap="medium" giãn khoảng cách; loop quay vòng ở hai đầu.

Phím tắt

Nhấn Ctrl + K để mở bảng lệnh ở bất kỳ đâu.

Chủ đề tối

Đổi Web Light / Web Dark ngay trong khung ví dụ.

Brand cục bộ

Đặt data-brand trên phần tử để đổi màu cho một vùng.

Autoplay có tiến độ

Chấm đang chọn dài ra và đầy dần theo autoplayInterval; rê chuột / focus vào slide hoặc ẩn tab là tạm dừng.

Mountains at dawn
Hills at sunset
Pine forest
Lake at night
Desert

Ảnh thu nhỏ

CarouselThumbnails thay cho chấm: tablist ảnh nhỏ, tự cuộn tới ảnh đang chọn; đặt aria-label từng ảnh.

Cách dùng

Nên
  • Đặt aria-label cho Carousel; mỗi slide tự có nhãn “Slide x / n”, thumbnail nên có aria-label riêng.
  • Giữ 3–6 slide cùng loại; dùng slidesPerView lẻ (1.15, 2.5) để gợi ý còn nội dung phía sau.
  • Khi bật autoplay, luôn hiện nút tạm dừng (CarouselNavContainer showAutoplayToggle).
Không nên
  • Không đặt thông tin quan trọng duy nhất trong slide ẩn.
  • Không bật autoplay mặc định cho nội dung cần đọc kỹ.
  • Không dùng cả chấm và thumbnail cho cùng một Carousel.

Props

Prop · KiểuMặc địnhMô tả
loopbooleanMặc định: falseQuay vòng ở hai đầu. Tên cũ circular đã lỗi thời (bỏ ở 1.0).
slidesPerViewnumberMặc định: —Số slide thấy cùng lúc; số lẻ để lộ slide kế (1.15, 2.5). Bỏ trống = 100%.
gap"none" | "extra-small" | "small" | "medium" | "large" | "extra-large"Mặc định: "small"Khoảng cách giữa các slide (token spacing). Tên ngắn cũ "XS" … "XL" đã lỗi thời (bỏ ở 1.0).
autoplay / defaultAutoplay / onAutoplayChangeboolean / boolean / (value) => voidMặc định: — / falseTự chạy (controlled / uncontrolled). defaultAutoplay bị bỏ qua khi prefers-reduced-motion.
autoplayIntervalnumberMặc định: 4000Thời gian mỗi slide (ms); tiến độ hiện trong chấm / thumbnail đang chọn.
activeIndex / defaultActiveIndex / onActiveIndexChangenumber / number / (index: number) => voidMặc định: — / 0Slide hiện tại, đếm từ 0 (controlled / uncontrolled); gọi khi slide hiện tại thay đổi.
CarouselCard.classNamestringMặc định: —basis-full mặc định; basis-4/5 hoặc basis-1/2 khi không dùng slidesPerView.
CarouselNavContainer.showAutoplayTogglebooleanMặc định: falseHiện nút bật / tắt tự chạy. Tên cũ autoplay đã lỗi thời (bỏ ở 1.0).
CarouselNavContainer.previousLabel / nextLabelstringMặc định: "Previous slide" / "Next slide"aria-label cho nút điều hướng. Tên cũ prevLabel đã lỗi thời (bỏ ở 1.0).
CarouselThumbnails / CarouselThumbnailHTMLAttributes / ButtonHTMLAttributesMặc định: —Tablist ảnh thu nhỏ; mỗi CarouselThumbnail ứng với slide cùng vị trí.

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.carousel

Khoá · KiểuMặc định (tiếng Anh)messagesVi
slide(index: number, count: number) => string

Tên từng slide / chấm / thumbnail và thông báo slide hiện tại; index đếm từ 1.

Mặc định (tiếng Anh)(index, count) => `Slide ${index} of ${count}`messagesVi(index, count) => `Slide ${index} / ${count}`
roleDescriptionstring

aria-roledescription của vùng carousel.

Mặc định (tiếng Anh)"carousel"messagesVi"carousel"
slideRoleDescriptionstring

aria-roledescription của từng slide.

Mặc định (tiếng Anh)"slide"messagesVi"slide"
previousstring

aria-label nút slide trước.

Mặc định (tiếng Anh)"Previous slide"messagesVi"Slide trước"
nextstring

aria-label nút slide sau.

Mặc định (tiếng Anh)"Next slide"messagesVi"Slide tiếp theo"
autoplaystring

aria-label nút bật / tắt tự chạy.

Mặc định (tiếng Anh)"Autoplay"messagesVi"Tự động chạy"
chooseSlidestring

aria-label dãy chấm / thumbnail (tablist).

Mặc định (tiếng Anh)"Choose slide"messagesVi"Chọn slide"