Component / 057 / NEXOFRAME

StepIndicator

Mẫu chuẩn

Dải chỉ báo các bước của một luồng: tên từng bước, bước hiện tại, bước đã xong, và dòng "Bước n / N". Mặc định chỉ để hiển thị. Nếu host truyền onStepSelect, các bước đã xong trở thành nút để quay lại. Dựng trên Progress.

Composite tầng 2Dựng từ Progress3–7 bướconStepSelect tuỳ chọn

Playground

Bật "Cho quay lại" rồi bấm một bước đã xong để nhảy về đó.

Bước 2 / 4

Kênh & tri thức
Giới hạn quyền
Chạy thử

import { StepIndicator } from "@nexobox/ui";

const [current, setCurrent] = useState(1);

<StepIndicator
  steps={[
    { id: "role", label: "Vai trò & nhiệm vụ" },
    { id: "channels", label: "Kênh & tri thức" },
    { id: "authority", label: "Giới hạn quyền" },
    { id: "trial", label: "Chạy thử" },
  ]}
  current={current}
  onStepSelect={setCurrent}
/>

Bài toán

Trong một luồng nhiều bước, người dùng cần biết còn bao nhiêu bước và mình đang ở đâu, và phải quay lại được bước trước mà không mất dữ liệu. Progress cho một thanh, nhưng không có tên bước, không có trạng thái từng bước, không có ngữ nghĩa danh sách có thứ tự.

Khi nào sử dụng

Nên dùng

Luồng 3–7 bước có thứ tự cố định. Đầu một dialog hoặc trang wizard.

Khi nào không dùng

Tránh dùng

Không dùng cho	Dùng thay
Tiến độ một tác vụ	Progress
Điều hướng giữa các trang ngang hàng	Tabs
Vị trí trong cây trang	Breadcrumb

Dựng từ

Primitive tầng 1	Vai trong composite
Progress	Thanh tiến độ tổng (value = bước hiện tại / tổng số bước)

StepIndicator thêm gì
Danh sách `<ol>` các bước có tên; bước hiện tại mang `aria-current="step"`
Dòng "Bước n / N" đọc được
Bước đã xong thành nút quay lại khi có `onStepSelect`

Anatomy

#	Phần	Ghi chú
1	Dòng đếm	"Bước n / N", đổi qua `counterLabel`
2	Progress	`value` = bước hiện tại, `max` = tổng số bước
3	Danh sách bước	Tên từng bước, dấu tích cho bước đã xong

States

Trạng thái của một bước	Biểu hiện
Đã xong	Dấu tích, chữ `text-secondary`; là nút khi có `onStepSelect`
Hiện tại	Chữ `text-primary`, đậm, `aria-current="step"`
Chưa tới	Chữ `text-muted`

Bàn phím & trợ năng

Tab tới bước đã xong, Enter quay lại -- composite, chỉ khi có onStepSelect.

Không có onStepSelect -- các bước không nhận tiêu điểm.

Seam — host sở hữu gì

Composite không giữ bước hiện tại và không kiểm bước có hợp lệ không. Host sở hữu current, quyết định có cho quay lại không, và giữ dữ liệu của các bước.

API & triển khai

Prop	Mặc định	Quy ước
steps	—	Bắt buộc. 3–7 bước.
current	—	Bắt buộc. Chỉ số bắt đầu từ 0.
onStepSelect	undefined	Chỉ các bước trước current gọi được.
counterLabel	"Bước n / N"	Câu chữ của dòng đếm (chỉ dạng ngang).
orientation	"horizontal"	"vertical": cột bên, mỗi bước có chấm, tên (xuống dòng khi hẹp, không bị cắt), một dòng tóm tắt (steps[].description) và chấm cảnh báo (steps[].warning); không có thanh tiến độ.
warningLabel	"cần xử lý"	Từ đọc cho bước có warning.

Design tokens

--nf-semantic-text-primary, --nf-semantic-text-secondary, --nf-semantic-text-muted, --nf-semantic-status-success-icon (dấu tích), --nf-foundation-typography-caption-*, --nf-foundation-typography-ui-*, --nf-foundation-space-2, --nf-foundation-space-3, --nf-component-focus-*. Qua Progress: --nf-component-progress-*.

Do / Don't

Nên dùng

Tên bước là việc sẽ làm: "Giới hạn quyền". Cho quay lại bước đã xong, giữ dữ liệu. Số bước lấy từ đặc tả của luồng.

Tránh dùng

Tên bước kiểu "Bước 3". Cho nhảy tới bước chưa tới. Cố định bốn bước như kit.