Giao diện
@digiforce-nc/plugin-block-grid-card
Plugin hiển thị dữ liệu collection dưới dạng lưới thẻ (Grid Card) - biến mỗi bản ghi thành một thẻ trực quan, sắp xếp theo lưới responsive tự động co giãn theo kích thước màn hình.
Plugin này làm gì?
Trong các ứng dụng quản lý dữ liệu, bảng (table) là cách hiển thị phổ biến nhưng không phải lúc nào cũng trực quan. Grid Card biến mỗi bản ghi thành một thẻ (card) với layout tùy chỉnh, sắp xếp trong lưới responsive - lý tưởng cho danh mục sản phẩm, thư viện ảnh, danh bạ nhân viên.
Ba nhiệm vụ chính
| # | Nhiệm vụ | Chi tiết |
|---|---|---|
| 1 | Hiển thị lưới thẻ responsive | Tự động điều chỉnh số cột theo breakpoint (xs, sm, md, lg, xl, xxl) |
| 2 | Phân trang thông minh | Hỗ trợ cả hai chế độ: biết tổng số (known count) và không biết tổng số (unknown count) |
| 3 | Tích hợp drag & drop | Cho phép kéo thả để sắp xếp lại thứ tự thẻ thông qua DnD actions |
Kiến trúc
Tổng quan
Plugin hoạt động hoàn toàn ở phía client - không có server component hay database riêng. Nó đọc dữ liệu từ collection API có sẵn và render dưới dạng grid card.
Widget hierarchy
| Widget | Kế thừa từ | Vai trò |
|---|---|---|
GridCardBlockWidget | CollectionBlockWidget | Block chính, quản lý resource, pagination, toolbar |
GridCardItemWidget | CollectionBlockWidget | Đại diện một thẻ, chứa layout fields bên trong |
Cơ chế responsive
Plugin sử dụng hệ thống breakpoint của Ant Design Grid để tự động điều chỉnh số cột:
| Breakpoint | Kích thước màn hình | Số cột mặc định |
|---|---|---|
xs | < 576px | 1 |
sm | >= 576px | 2 |
md | >= 768px | 3 |
lg | >= 992px | 3 |
xl | >= 1200px | 4 |
xxl | >= 1600px | 4 |
Admin có thể tùy chỉnh số cột cho từng breakpoint qua Settings panel.
Tính năng
| Tính năng | Mô tả |
|---|---|
| Responsive grid | Số cột tự động thay đổi theo breakpoint, cấu hình được |
| Pagination | Phân trang với hai chế độ known/unknown count |
| Card designer | Kéo thả field vào card template, tùy chỉnh layout |
| DnD reorder | Sắp xếp lại thứ tự thẻ bằng drag & drop |
| Toolbar actions | Filter, sort, bulk actions trên toolbar |
| Multi data source | Hoạt động với mọi data source đã đăng ký |
| Association support | Hiển thị grid card trong popup association |
Luồng hiển thị dữ liệu
Thành phần client
| Thành phần | Mô tả |
|---|---|
GridCardBlockWidget | Widget chính, extends CollectionBlockWidget, quản lý grid layout |
GridCardItemWidget | Widget thẻ con, render từng bản ghi theo card template |
GridCard | Component React render lưới thẻ với Ant Design List.Grid |
GridCardDesigner | Designer cho phép cấu hình columns, breakpoints |
GridCardBlockInitializer | Initializer đăng ký block vào menu "Add block" |
gridCardActionInitializers | Nhóm action khả dụng: filter, sort, refresh, bulk |
GridCardItemActionInitializers | Action trên từng thẻ: view, edit, delete, custom |
Dependencies
| Package | Vai trò |
|---|---|
@digiforce-nc/client | Client framework, widget system (peer) |
@digiforce-nc/server | Server framework - chỉ dùng khi build (peer) |
antd | Ant Design - Grid, List, Card components (peer) |
@dnd-kit/core | Drag & drop framework cho reorder thẻ |