Component / 067 / NEXOFRAME

FileDropBar

Mẫu chuẩn

Biến thể gọn một dòng của FileDrop, dùng khi danh sách tài liệu đã có hàng và ô kéo-thả lớn không còn xứng đáng chiếm chỗ. Ba trạng thái: idle, dragover (tự quản bởi component), error (do host điều khiển qua prop state).

Composite tầng 2Không dựng từ composite khác3 stateK8 — redesign Tài liệu Crew

Playground

Kéo một tệp thật vào thanh để thấy trạng thái dragover (component tự quản). Chọn "error" để thấy dòng lỗi dưới thanh.

Chưa chọn tệp nào.

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

<FileDropBar
  accept={[".pdf", ".docx", ".xlsx", ".csv", ".txt", ".md"]}
  maxBytes={20 * 1024 * 1024}
  state="idle"
  onFiles={(files) => handleFiles(files)}
>
  Thêm tài liệu
</FileDropBar>

Bài toán

K8 giữ FileDrop làm điểm neo duy nhất khi danh sách rỗng, nhưng khi danh sách đã có tài liệu, ô lớn đó đẩy nội dung chính xuống dưới màn hình đầu tiên mà không thêm giá trị.

Khi nào sử dụng

Nên dùng

Trang "Tài liệu" của Crew khi danh sách tài liệu không rỗng: một thanh gọn phía trên danh sách.

Khi nào không dùng

Tránh dùng

Không dùng cho	Dùng thay
Danh sách rỗng	FileDrop -- ô lớn vẫn là điểm neo thị giác duy nhất khi chưa có nội dung nào khác để nhìn

Anatomy

#	Phần	Ghi chú
1	Vùng bấm/kéo-thả	`<button type="button">` một dòng, viền mảnh, bọc `<input type="file" hidden>`
2	Icon	`FileValidationIcon`, kích thước nhỏ
3	Nhãn	`children`, một dòng
4	Gợi ý / lỗi	Gợi ý mặc định suy từ `maxBytes`, bên phải; dòng lỗi đỏ dưới thanh khi `error`

States

State	Kích hoạt bởi	Hành vi
idle	Mặc định	Viền `border-subtle`, đổi `border-strong` khi hover
dragover	Component tự quản	Viền `border-strong`, nền `surface-subtle`, vòng `box-shadow` mờ -- không đổi chiều cao (UI-PERF quy tắc 6)
error	Host truyền `state="error"` + `errorMessage`	Viền `status-danger-border`, dòng lỗi `role="alert"` dưới thanh

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

Tab tới thanh; Enter/Space mở hộp thoại chọn tệp (hành vi gốc của <button>).

aria-describedby trỏ tới gợi ý hoặc thông báo lỗi đang hiển thị.

Seam — host sở hữu gì

Giống FileDrop: FileDropBar không gọi server và không enforce maxBytes -- nó chỉ đưa File[] qua onFiles. Host tự tải lên và tự soạn errorMessage.

API & triển khai

Prop	Mặc định	Quy ước
accept	—	Bắt buộc. Mảng mime hoặc phần mở rộng, truyền thẳng vào input[accept].
maxBytes	—	Bắt buộc. Chỉ dùng để suy gợi ý mặc định -- không lọc tệp.
multiple	true	Khác FileDrop (mặc định false) -- một thanh thêm tài liệu thường nhận nhiều tệp một lúc.
disabled	false	Vô hiệu cả bấm lẫn kéo-thả.
onFiles	—	Bắt buộc. (files: File[]) => void.
state	"idle"	"idle" \| "dragover" \| "error". dragover thường để component tự set.
errorMessage	undefined	Hiện khi state="error".
hint	suy từ maxBytes	Ghi đè gợi ý mặc định.
children	—	Bắt buộc. Nhãn một dòng.

Design tokens

--nf-component-field-radius, --nf-foundation-space-4, --nf-foundation-space-2, --nf-semantic-border-subtle, --nf-semantic-border-strong, --nf-semantic-surface-raised, --nf-semantic-surface-subtle, --nf-semantic-status-danger-border, --nf-semantic-status-danger-foreground, --nf-semantic-text-primary, --nf-semantic-text-muted.

Do / Don't

Nên dùng

Dùng khi danh sách đã có hàng -- để FileDrop lớn cho danh sách rỗng.

Tránh dùng

Dựa vào FileDropBar để chặn tệp quá khổ -- maxBytes không lọc, chỉ gợi ý.