Giao diện
@digiforce-nc/plugin-calendar
Plugin hiển thị dữ liệu collection dưới dạng lịch (Calendar View) - hỗ trợ chế độ xem ngày/tuần/tháng, sự kiện lặp lại (cron), và tích hợp lịch âm dương.
Plugin này làm gì?
Calendar block biến collection có trường ngày thành giao diện lịch trực quan. Mỗi bản ghi trở thành một sự kiện trên lịch, có thể xem theo ngày, tuần hoặc tháng. Plugin hỗ trợ sự kiện lặp lại qua cron expression, loại trừ ngày cụ thể, và hiển thị lịch âm (lunar calendar).
Ba nhiệm vụ chính
| # | Nhiệm vụ | Chi tiết |
|---|---|---|
| 1 | Hiển thị lịch | Chế độ xem ngày/tuần/tháng với react-big-calendar |
| 2 | Sự kiện lặp lại | Cron expression cho repeat, loại trừ ngày cụ thể |
| 3 | Tương tác sự kiện | Tạo/sửa event từ popup, kéo thả thay đổi ngày |
Kiến trúc
Tổng quan
Plugin có server stub (đăng ký plugin) và client phong phú. Dữ liệu calendar đọc từ collection API, cron repeat xử lý client-side.
| Tầng | Vai trò | Thành phần |
|---|---|---|
| Client UI | Render lịch, popup tạo/sửa event | CalendarV2, CalendarBlockProvider |
| Server | Stub - đăng ký plugin | Server class rỗng |
| Collection API | Cung cấp dữ liệu event | Collection có date field |
Calendar template collection
Plugin hoạt động tốt nhất với collection sử dụng calendar template - bổ sung các field cron và exclude cho sự kiện lặp:
| Field | Kiểu | Mô tả |
|---|---|---|
cron | string | Cron expression cho sự kiện lặp lại |
exclude | JSON | Mảng ngày bị loại trừ khỏi lịch lặp |
Luồng hiển thị lịch
Tính năng
| Tính năng | Mô tả |
|---|---|
| Day view | Xem lịch theo ngày, timeline chi tiết |
| Week view | Xem lịch theo tuần, 7 cột |
| Month view | Xem lịch theo tháng, tổng quan |
| Cron repeat | Sự kiện lặp lại theo cron expression |
| Exclude dates | Loại trừ ngày cụ thể khỏi lịch lặp |
| Event popup | Popup tạo/sửa event khi click |
| Color field | Tô màu event theo field (status, category) |
| Title field | Cấu hình field hiển thị làm tiêu đề event |
| Lunar calendar | Hiển thị ngày âm lịch (solarlunar-es) |
| Association calendar | Calendar block cho association data |
| Drag reschedule | Kéo event để thay đổi ngày/giờ |
| Cron editor | UI editor cho cron expression (react-js-cron) |
Thành phần client
| Thành phần | Mô tả |
|---|---|
CalendarBlockWidget | Widget chính đăng ký Calendar block |
CalendarBlockProvider | Provider quản lý state: view mode, date range, events |
CalendarV2 | Component lịch chính bọc react-big-calendar |
CalendarToolbar | Toolbar: chuyển view mode, navigation ngày |
CalendarEventPopup | Popup tạo/sửa event |
CronEditor | UI component chỉnh sửa cron expression |
CalendarBlockInitializer | Đăng ký vào menu "Add block" |
CalendarDesigner | Designer: cấu hình title/start/end/color fields |
Cấu hình block
| Setting | Mô tả | Mặc định |
|---|---|---|
| Title field | Field hiển thị làm tiêu đề event | title |
| Start date field | Field ngày bắt đầu | startDate hoặc createdAt |
| End date field | Field ngày kết thúc | endDate |
| Color field | Field xác định màu event | Không có |
| Default view | Chế độ xem mặc định | Month |
| Show lunar | Hiển thị ngày âm lịch | false |
Dependencies
| Package | Vai trò |
|---|---|
@digiforce-nc/client | Client framework (peer) |
@digiforce-nc/server | Server framework (peer) |
react-big-calendar | Thư viện lịch React chính |
dayjs | Thư viện xử lý ngày tháng |
cron-parser | Parse cron expression cho event lặp |
react-js-cron | UI component chỉnh sửa cron |
solarlunar-es | Chuyển đổi dương lịch ↔ âm lịch |