English
Vietnamese@ark-ui/react/popover + Tailwind CSS v4
Ark Popover
Thành phần Popover đa dụng tương tác cao được xây dựng trên nền tảng máy trạng thái Ark UI (Zag.js engine) và tạo kiểu toàn diện với Tailwind CSS v4. Hỗ trợ đầy đủ chuẩn tiếp cận WAI-ARIA, định vị thông minh Floating UI (flip & shift), tách biệt Trigger và Anchor (Custom Anchor), quản lý focus trap (Modal mode), mũi tên định hướng đồng bộ và hỗ trợ cả hai mô hình: Tiện ích cấp cao (Convenience API) và Cấu trúc ghép nối linh hoạt (Compound Component API).
1. Cơ bản (Basic Usage)
Sử dụng cú pháp tiện ích cấp cao để hiển thị popover chứa form nhập kích thước khi người dùng click vào nút.
Kích thước ảnh
Điều chỉnh chiều rộng và chiều cao cho ảnh xem trước.
2. Kích thước (Sizes)
Cung cấp 5 kích thước chuẩn hóa: sm (w-64), md (w-80, mặc định), lg (w-96), xl (w-112) và auto (tự co giãn).
Kích thước: SM
Độ rộng tối đa w-64 (256px), thích hợp menu nhỏ gọn.
Phần tử đang hiển thị với lớp kích thước chuẩn trong hệ thống ArkPopover.
Kích thước: MD
Độ rộng tối đa w-80 (320px), chuẩn mặc định.
Phần tử đang hiển thị với lớp kích thước chuẩn trong hệ thống ArkPopover.
Kích thước: LG
Độ rộng tối đa w-96 (384px), thích hợp form ngắn.
Phần tử đang hiển thị với lớp kích thước chuẩn trong hệ thống ArkPopover.
Kích thước: XL
Độ rộng tối đa w-112 (448px), thích hợp nội dung lớn.
Phần tử đang hiển thị với lớp kích thước chuẩn trong hệ thống ArkPopover.
Kích thước: AUTO
Tự động co giãn theo nội dung bên trong.
Phần tử đang hiển thị với lớp kích thước chuẩn trong hệ thống ArkPopover.
3. Biến thể phong cách (Variants)
Đa dạng biến thể bề mặt: default (surface-raised), subtle, elevated (surface-floating), glass (kính mờ) và solid.
Biến thể: Default
Màu nền surface-raised và viền chuẩn hệ thống.
Giao diện tự động thích ứng với cả chế độ Light và Dark.
Biến thể: Subtle
Màu nền nhẹ nhàng, bóng mờ dịu mắt.
Giao diện tự động thích ứng với cả chế độ Light và Dark.
Biến thể: Elevated
Nổi bật với nền surface-floating và shadow 2xl.
Giao diện tự động thích ứng với cả chế độ Light và Dark.
Biến thể: Glass
Hiệu ứng kính mờ thời thượng với backdrop-blur-md.
Giao diện tự động thích ứng với cả chế độ Light và Dark.
Biến thể: Solid
Tông đen/trắng tương phản cao sắc nét.
Giao diện tự động thích ứng với cả chế độ Light và Dark.
4. Vị trí hiển thị (Placements)
Hỗ trợ 8 hướng neo vị trí khác nhau kèm thuật toán tự động tránh tràn viền màn hình (Flip & Shift).
Hướng: Top
Được tính toán động bởi engine định vị Floating UI.
Tự động dịch chuyển (shift) và lật (flip) nếu không đủ khoảng trống trên khung nhìn.
Hướng: Top Start
Được tính toán động bởi engine định vị Floating UI.
Tự động dịch chuyển (shift) và lật (flip) nếu không đủ khoảng trống trên khung nhìn.
Hướng: Top End
Được tính toán động bởi engine định vị Floating UI.
Tự động dịch chuyển (shift) và lật (flip) nếu không đủ khoảng trống trên khung nhìn.
Hướng: Bottom
Được tính toán động bởi engine định vị Floating UI.
Tự động dịch chuyển (shift) và lật (flip) nếu không đủ khoảng trống trên khung nhìn.
Hướng: Bottom Start
Được tính toán động bởi engine định vị Floating UI.
Tự động dịch chuyển (shift) và lật (flip) nếu không đủ khoảng trống trên khung nhìn.
Hướng: Bottom End
Được tính toán động bởi engine định vị Floating UI.
Tự động dịch chuyển (shift) và lật (flip) nếu không đủ khoảng trống trên khung nhìn.
Hướng: Left
Được tính toán động bởi engine định vị Floating UI.
Tự động dịch chuyển (shift) và lật (flip) nếu không đủ khoảng trống trên khung nhìn.
Hướng: Right
Được tính toán động bởi engine định vị Floating UI.
Tự động dịch chuyển (shift) và lật (flip) nếu không đủ khoảng trống trên khung nhìn.
5. Mũi tên chỉ hướng (With & Without Arrow)
Tùy chọn hiển thị hoặc ẩn mũi tên chỉ hướng (hasArrow: true/false) đồng bộ màu nền và viền chuẩn xác.
Có mũi tên (Mặc định)
Mũi tên giúp người dùng nhận biết rõ ràng phần tử kích hoạt nguồn.
Mũi tên định hướng tự động xoay và gắn liền với vị trí của trigger.
Không có mũi tên
Phong cách phẳng, tối giản cho các menu dạng bảng trôi nổi.
Phù hợp với giao diện minimalist hoặc các menu thả xuống không cần trỏ.
6. Bộ lọc nâng cao trong Popover (Form Filter)
Ứng dụng popover chứa form tìm kiếm từ khóa và chọn trạng thái lọc, có nút đặt lại và áp dụng tiện lợi.
Bộ lọc bài viết
Lọc danh sách bài viết theo từ khóa và trạng thái xuất bản.
Trạng thái
7. Xác nhận hành động nhạy cảm (Confirm Action)
Thay thế dialog toàn màn hình bằng popover xác nhận xóa ngay tại vị trí nút kích hoạt.
Xác nhận xóa?
Hành động này sẽ chuyển tệp vào thùng rác và không thể hoàn tác trực tiếp.
Các liên kết đang sử dụng tệp này có thể bị gián đoạn.
8. Điều khiển trạng thái (Controlled Mode)
Quản lý việc mở/đóng popover từ bên ngoài bằng React State kết hợp thuộc tính open và sự kiện onOpenChange.
open: false
Trạng thái có kiểm soát (Controlled Mode)
Được quản lý thông qua React state [open, setOpen] đồng bộ 2 chiều.
Giá trị hiện tại của open là: false
Khi người dùng bấm ra ngoài hoặc bấm phím ESC, sự kiện onOpenChange sẽ cập nhật lại state.
Lưu ý kỹ thuật: Sử dụng persistentElements hoặc onInteractOutside cho nút bấm bên ngoài để ngăn sự kiện pointerdown outside kích hoạt đóng popover trước khi onClick kịp thực thi.
9. Tách biệt Trigger và Anchor (Custom Anchor)
Sử dụng ArkPopover.Anchor để neo vị trí popover vào một input cụ thể, trong khi nút kích hoạt (Trigger) nằm ở vị trí khác.
ReactTailwind CSS
Các thẻ phổ biến gợi ý
10. Chế độ Modal (Focus Trap Mode)
Bật modal={true} để giữ tiêu điểm bàn phím an toàn bên trong popover và ngăn chặn các click nhầm ra ngoài.
Bảo mật: Xác nhận mã PIN
Khi ở chế độ modal={true}, tiêu điểm bàn phím sẽ được giữ an toàn bên trong popover.
Chế độ này ngăn chặn click nhầm ra các phần tử nền bên ngoài.
11. Cấu trúc ghép nối (Compound Component API)
Kiểm soát toàn diện từng phần tử với ArkPopover.Root, Trigger, Positioner, Content, Header, Title, Description, CloseTrigger, Body, Footer.
Compound Component API
Cấu trúc linh hoạt tối đa với các thành phần ghép nối độc lập.
Các phần tử có thể tái cấu trúc:
- Root & RootProvider
- Trigger & Anchor
- Positioner & Portal
- Content, Arrow & ArrowTip
- Header, Title, Description
- CloseTrigger, Body, Footer
12. Cấu hình cá nhân nhanh (Quick User Settings)
Thẻ thông tin người dùng mini với avatar, huy hiệu phân quyền, email, các công tắc bật/tắt thiết lập nhanh và nút đăng xuất.
AD
Admin ChillCMS
Super Adminadmin@chillcms.dev