Yugen UI

PageProgress

Thanh tiến trình mảnh màu brand ở mép trên trang: báo ứng dụng đang làm việc khi chuyển route hay tải nền, mà không che nội dung đang đọc.

Hai chế độ: xác định (value 0–1) khi biết tiến độ thật, và trickle (active) tự nhích dần tới ~94% rồi chạy nốt 100% và mờ đi khi xong. Bộ điều khiển mệnh lệnh pageProgress.start() / .done() / .set(n) gọi được ở bất kỳ đâu (router, lớp bọc fetch) mà không cần context; start/done được đếm nên nhiều tác vụ chồng nhau vẫn kết thúc đúng lúc. Tôn trọng prefers-reduced-motion: không chuyển động độ rộng, không fade.

Tổng quan

Nội dung trang cũ ở nguyên chỗ trong lúc trang mới tải.

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 { PageProgress, PageProgressFallback, pageProgress, usePageProgress } 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.

Chưa có tệp

Xác định (value)

Biết tiến độ thật (tải tệp lên) thì truyền value; kèm active để thanh chỉ hiện trong lúc tải.

Thanh chạy ở mép trên cửa sổ. Bấm nhiều lần: thanh chỉ hoàn tất khi mọi lần đồng bộ đã xong.

Bộ điều khiển mệnh lệnh

Trong ứng dụng: gắn một <PageProgress /> ở gốc rồi gọi pageProgress.start() / .done(). Ví dụ dùng createPageProgress() riêng để không đụng thanh của trang docs.

Suspense & route lazy

PageProgressFallback làm fallback của Suspense: thanh chạy suốt lúc chunk đang tải, không spinner giữa trang.

Cách dùng

Nên
  • Gắn một PageProgress ở gốc ứng dụng và điều khiển bằng pageProgress hoặc PageProgressFallback.
  • Dùng value khi có tiến độ thật; trickle khi chỉ biết “đang chạy”.
  • Giữ nội dung trang cũ trong lúc tải trang mới.
Không nên
  • Không dùng PageProgress cho thao tác cục bộ trong một vùng — dùng LoadingOverlay hoặc Button loading.
  • Không quên gọi done() trong finally — thanh sẽ dừng ở ~94% mãi.
  • Không đặt thanh dày hay màu trạng thái; đây là tín hiệu nền, không phải thông báo.

Props

Prop · KiểuMặc địnhMô tả
valuenumberMặc định: —0–1, chế độ xác định; ≥ 1 → hoàn tất rồi mờ đi.
activebooleanMặc định: —true → hiện (trickle nếu không có value); false → chạy tới 100% rồi mờ đi.
controllerPageProgressControllerMặc định: pageProgressBộ điều khiển dùng khi không truyền value / active.
position"fixed" | "absolute"Mặc định: "fixed"fixed: mép trên khung nhìn (portal, z-50) · absolute: mép trên phần tử cha relative.
thickness"medium" | "large"Mặc định: "medium"2px / 4px.
labelstringMặc định: "Loading page"aria-label của progressbar.
pageProgress.start() / .done() / .set(n) / .reset()PageProgressControllerMặc định: —Điều khiển mệnh lệnh; start/done được đếm. createPageProgress() tạo bộ riêng.
PageProgressFallback / usePageProgress(active?)component / hookMặc định: —Chạy thanh suốt lúc mount (fallback của Suspense) hoặc trong lúc active.

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

Khoá · KiểuMặc định (tiếng Anh)messagesVi
labelstring

aria-label của progressbar.

Mặc định (tiếng Anh)"Loading page"messagesVi"Đang tải trang"