项目体验

Design System · Scheduling Component

npm-ready TypeScript Strict Ant Design 5

ChessboardLayout
v2.0

通用「资源 × 时间」二维棋盘布局组件 · Universal Resource × Time Scheduler

一个不绑定具体业务的 React 调度布局组件,支持时间纵轴 timeY 与时间横轴 timeX,可用于场地预订、宠物寄养、美发预约、会议室和医疗排班。组件提供 TypeScript 类型、Render Props 与交互回调,方便接入不同产品。

版本 v2.0.0
定位 设计系统组件库
依赖 React 18 · AntD 5 · dayjs
验证场景 场地/宠物/美发/会议/医疗
设计思路

Design Philosophy

为什么要抽成通用组件

调度页面经常重复处理资源、时间、事件重叠、状态和拖拽。ChessboardLayout 将这些布局与交互能力抽成可配置组件,上层产品只需要传入数据并处理自己的业务规则。

2
轴模式 timeY / timeX
5
时间颗粒度(15m~1天)
20+
可调配置开关
3
内置场景 Demo 预设

Axis Modes

双轴模式设计

通过 axisMode 切换时间方向:日内精细排期使用纵轴,多日资源排期使用横轴。

timeY
时间 → 纵轴
资源为列(横排),时间从上往下流动。参考:Google Calendar 周视图、Calendly 预约选时。适合当日内精细时间管理。
🏸 场地预订 ✂️ 美发/美甲 🏥 医生排班 🤝 会议室
timeX
时间 → 横轴
资源为行(竖排),时间从左往右流动。参考:FullCalendar Timeline、Notion 日历、项目甘特图。适合多日跨度排期。
🐾 宠物寄养 🏨 酒店排期 📊 项目甘特 🛏️ 病床管理

Time Granularity

15min
快剪 / 美甲
精细时间粒度
30min
理发 / 按摩
标准服务粒度
60min
场地 / 会议室
按小时预约
120min
游乐场 / 设备
固定时段预约
1440min
宠物寄养 / 酒店
按日甘特图

Built-in Scenarios

三个场景预设

三套预设分别检查按小时、按天和高密度预约的布局表现,并展示资源、事件、状态与配置项如何组合。

Scenario A · 场地预订
综合体育馆
羽毛球(3场)· 网球(2场)· 篮球场 · 台球室,展示按小时预约、价格标签、容量进度条、维护状态
axisMode timeY
granularity 60 min
slotSize 72 px
showSlotPrice true
showCapacityBar true
enableResourceGroups true
resources 7 × CbResource
events 28 × CbEvent
Scenario B · 宠物寄养
星宠酒店(14日)
小型犬/中型犬/大型犬/猫咪4分组,14天跨度视图,展示多区折叠、按天粒度、泳道并排
axisMode timeX
granularity 1440 min (1天)
rangeEnd 14 × 1440 = 14天
showWeekendHighlight true
collapsibleGroups true
groups 4 × CbResourceGroup
resources 9 × CbResource
events 29 × CbEvent
Scenario C · 美发预约
风尚发型工作室
5位发型师 · 30分钟颗粒度 · 显示资源标签(烫/染/快剪)· 展示密集预约泳道并排
axisMode timeY
granularity 30 min
slotSize 48 px
showResourceTags true
overlapStyle "lanes"
showCurrentTimeLine true
resources 5 × CbResource
events 29 × CbEvent

Component Architecture

组件与业务如何分工

组件负责布局、状态显示和交互事件,业务层负责数据来源、权限和规则判断。四个核心类型定义了两者之间的接口。

🏗️
CbResource
资源实体定义。支持标签、副标题、头像、颜色、容量(多预约叠加)、禁用状态与扩展字段。
export interface CbResource
📅
CbEvent
预约事件块。以分钟绝对值表示时间(09:00=540),支持颜色、状态标签、拖拽/缩放控制与扩展数据。
export interface CbEvent
🎨
ChessboardSlots
Render Props 插槽。renderEvent / renderResourceHeader / renderTimeLabel / renderSlotBackground,均有默认实现,按需覆盖。
export interface ChessboardSlots
ChessboardCallbacks
交互回调。onSlotClick / onSlotDoubleClick / onEventClick / onEventDragEnd / onEventResizeEnd,所有业务逻辑由上层实现。
export interface ChessboardCallbacks
格子状态(CbSlotStatus)
available
可预约
partial
部分占用
full
已满
unavailable
不可用
maintenance
维护中

Configuration System

八组配置项

ChessboardConfig 包含 20+ 个配置项,按轴方向、时间范围、尺寸、显示、事件样式、交互、分组和主题进行分类,并补充 JSDoc 说明。

§ A
轴 & 方向
axisMode: 'timeY' | 'timeX'
§ B
时间范围 & 颗粒度
rangeStartMinute
rangeEndMinute
granularity: 15|30|60|120|1440
§ C
格子 & 轴尺寸
slotSize (主轴格子 px)
resourceAxisSize (次轴 px)
timeHeaderSize / resourceHeaderSize
§ D
显示控制
showTimeAxis / showResourceAxis
showGridLines / showCurrentTimeLine
showSlotStatus / showSlotPrice
showCapacityBar / showResourceTags
showWeekendHighlight
§ E
事件视觉样式
eventStyle: solid|soft|outline|dot
eventBorderRadius
overlapStyle: lanes|stack|transparent
§ F
交互控制
readOnly / allowCreate
createTrigger: click|doubleClick
allowEventDrag / allowEventResize
allowCrossResourceDrag / snapMinutes
§ G
资源分组
enableResourceGroups
collapsibleGroups
§ H
外观主题
colorScheme: 'dark' | 'light'
自动跟随 AntD ConfigProvider
Token 映射,无硬编码色值

Tech Stack

实现与接入方式

组件读取 Ant Design ConfigProvider 中的颜色、圆角和间距 Token,并跟随产品主题变化。

React 18 TypeScript Strict Ant Design 5 dayjs useToken · useMemo · useRef Render Props Pattern Lane Algorithm (overlap) CSS position:sticky (frozen header) ConfigProvider Token Mapping pnpm workspace npm-ready
📦 交付方式 1
直接复制文件
单文件 + 配套类型文件,无需额外配置即可嵌入现有工程。
📦 交付方式 2
pnpm workspace 内部包
发布为 @workspace/chessboard-layout,在 monorepo 内跨项目复用。
📦 交付方式 3
Storybook Stories
导出 3 大场景为可视化 Storybook 文档,支持交互式配置面板演示。

Complete demo task

从切换调度模型开始,到冲突修正和状态更新。

产品范围是可复用的资源 × 时间调度模式;交互证据覆盖双轴、场景配置、搜索筛选、空时段创建、冲突校验与后续状态操作。

  1. 01 / Configure切换场景与轴向
  2. 02 / Find搜索与状态筛选
  3. 03 / Create选择空时段
  4. 04 / Recover修正冲突
  5. 05 / Manage确认、取消或删除

Case evidence / scheduling pattern

用同一套资源 × 时间模型覆盖多类调度场景,并补齐创建与状态闭环

我的角色是梳理双轴布局、事件状态、配置边界和交互反馈,并用独立 Demo 验证组件模式。当前案例呈现的是可运行原型与规则证据,不声称已发布为公共 npm 包。

01 / 背景与角色

资源类型不同,但调度判断相似

会议室、场地、服务人员和寄养房间都需要回答“谁、何时、什么状态”。我负责抽取共用模型、双轴显示与新建预约流程。

02 / 难点

密度、重叠、不可用与可访问操作

  • 横向和纵向模式要共享数据而不丢失状态。
  • 事件筛选后仍需保留空时段创建入口。
  • 鼠标悬停信息必须有键盘选择和显式操作面板补充。
03 / 关键决策

棋盘只负责判断,表单负责确认

空格点击进入新建表单;表单检查营业时间、不可用区间与冲突;选中已有事件后提供确认、取消和删除,而不是只显示一个 Toast。

04 / 组件系统关联

把轴向、状态色和操作反馈定义为契约

场景只提供资源、时间粒度、事件与不可用数据;按钮组、选择器、Modal、错误提示、Toast 和 Focus Ring 复用同一基础状态。

05 / 真实交付证据

四类演示数据与可完成操作

  • 可切换 timeX / timeY、事件样式与四类资源场景。
  • 可搜索、按状态筛选并恢复空结果。
  • 可触发冲突错误、调整时间、创建预约并继续更新状态。
06 / 结果表达

结果是沉淀了可复测的调度模式

交付证明了双轴显示与事件操作可以共享一套数据结构。这里不使用未经验证的性能提升、组件下载量或线上业务指标。

选择业务场景切换轴向 / 筛选点击空时段冲突校验与修正创建并更新状态

LIVE DEMO

体验 ChessboardLayout

可以切换 timeX / timeY、业务场景和事件样式,并直接点击格子与预约事件。

全屏体验 Demo ↗

ChessboardLayout · v2.0

面向多类资源调度场景的可配置组件,可作为内部包接入产品。

React 18 TypeScript Ant Design 5 Render Props 可发布 npm