Ark Collapsible
Thành phần thu gọn / mở rộng nội dung linh hoạt, xây dựng trên nền tảng Zag.js state machine. Đảm bảo hiệu ứng chuyển động chiều cao (height transition) mượt mà 100% bằng CSS Keyframes, hỗ trợ đầy đủ WAI-ARIA và không bao giờ bị giật hình khi đóng.
1. Phương thức sử dụng: Shorthand & Compound Anatomy
Hai mô hình APIArkCollapsible hỗ trợ cả cú pháp 1 dòng tiện ích lẫn cấu trúc Compound Components để tùy biến sâu.
Truyền các props như title, description, icon, badge trực tiếp vào component.
Sử dụng ArkCollapsible.Root, Trigger, Content và Indicator khi cần bố cục trigger đặc biệt.
Hệ thống đang sử dụng kết nối bảo mật SSL với cơ chế tái sử dụng kết nối nhằm tối ưu độ trễ truy vấn.
2. Ma trận kiểu dáng (Variants)
5 Biến thểKhám phá 5 phong cách trực quan từ tối giản, thẻ nổi cho đến hiệu ứng kính mờ (outline/backdrop blur).
3. Đồng bộ kích thước Controls (Sizes Matrix)
xs / sm / md / lgCả 4 kích cỡ (xs, sm, md, lg) được chuẩn hóa theo hệ thống token ControlSize của ChillCMS.
Chiều cao tối thiểu của Trigger tự động đồng bộ với min-h-(--spacing-control-height-md), giúp nút bấm căn đều hoàn hảo khi đứng cạnh các trường nhập liệu Input và Button.
So sánh trực tiếp cả 4 kích cỡ:
Nội dung mẫu với cỡ chữ và khoảng đệm tương ứng với cấp độ kích cỡ xs.
Nội dung mẫu với cỡ chữ và khoảng đệm tương ứng với cấp độ kích cỡ sm.
Nội dung mẫu với cỡ chữ và khoảng đệm tương ứng với cấp độ kích cỡ md.
Nội dung mẫu với cỡ chữ và khoảng đệm tương ứng với cấp độ kích cỡ lg.
4. Điều khiển trạng thái (Controlled Mode) & Machine Context
Controlled APIMở, đóng hoặc toggle từ bên ngoài thông qua React state hoặc truy cập ngữ cảnh máy trạng thái thời gian thực.
Trạng thái được đồng bộ hai chiều (Two-way sync):
[DETAILS]: Zag Presence Animation Lifecycle listening to CSS Keyframes
[WAI-ARIA]: aria-expanded=false
5. Kịch bản ứng dụng thực tế
Thực tếCác mô hình ứng dụng phổ biến: FAQ Accordion, JSON Code Viewer, Bộ lọc nâng cao và Collapsible lồng nhau.
Mô hình 1: Nhóm câu hỏi thường gặp (FAQ)
Hoàn toàn không. Máy trạng thái Zag.js đo lường chính xác kích thước thực tế của nội dung qua Resize Observer và gán biến CSS --height. Animation kết hợp CSS keyframes đảm bảo khung hình chuyển động ổn định 60fps mà không gây nhảy giật nội dung.
Có! Mỗi ArkCollapsible sở hữu một ID và scope Zag riêng biệt, do đó bạn có thể lồng nhiều cấp độ tùy ý mà không sợ bị xung đột sự kiện hay trạng thái đóng/mở.
Nội dung này không thể mở vì Collapsible đã được cấu hình thuộc tính disabled.
Mô hình 2: Trình xem cấu hình mã nguồn (Code Inspector)
{
"app": "ChillCMS",
"version": "2.4.0",
"features": {
"collapsible": true,
"presence": "zag.js",
"styling": "tailwind-v4"
},
"cache": {
"strategy": "memory",
"ttl": 3600
}
}Mô hình 3: Bộ lọc nâng cao (Advanced Filter Panel)
Mô hình 4: Collapsible lồng nhau (Cây tài nguyên)
6. Tra cứu Props & Cấu trúc thành phần (API Reference)
DocumentationToàn bộ props của ArkCollapsible, subcomponents và Zag state machine hook.
| Thuộc tính (Prop) | Kiểu dữ liệu (Type) | Mặc định | Mô tả |
|---|---|---|---|
| title | ReactNode | - | Tiêu đề của Collapsible khi dùng Shorthand API. |
| description | ReactNode | - | Mô tả phụ hiển thị bên dưới tiêu đề. |
| icon | ReactNode | - | Biểu tượng đầu dòng (Leading Icon). |
| badge | ReactNode | - | Huy hiệu trạng thái bên cạnh tiêu đề. |
| variant | 'default' | 'card' | 'bordered' | 'subtle' | 'outline' | 'ghost' | 'default' | Kiểu dáng hiển thị của component. |
| size | 'xs' | 'sm' | 'md' | 'lg' | 'md' | Kích cỡ của Trigger theo chuẩn ControlSize. |
| open | boolean | - | Trạng thái đóng/mở có kiểm soát (Controlled mode). |
| defaultOpen | boolean | false | Trạng thái mở mặc định khi khởi tạo. |
| onOpenChange | (details: CollapsibleOpenChangeDetails) => void | - | Callback kích hoạt khi trạng thái đóng/mở thay đổi. |
| disabled | boolean | false | Vô hiệu hóa tương tác đóng/mở của Trigger. |
| indicator | ReactNode | boolean | true | Hiển thị icon xoay tự động (true) hoặc tùy biến icon theo ý muốn. |