Design System · Component Library · AI Vibe Coding

npm-ready TypeScript Strict Ant Design 5

ChessboardLayout
v2.0

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

零业务逻辑的纯布局层 React 组件，双轴模式（时间纵轴 timeY / 时间横轴 timeX），覆盖场地预订、宠物寄养、美发预约、会议室、医疗排班等多种调度场景。完整 TypeScript 类型导出，Render Props + 回调架构，可直接发布为 npm 内部包嵌入设计系统。

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

Design Philosophy

设计理念

调度类组件是 SaaS 产品中最复杂的 UI 之一，几乎每个垂直场景都需要重写一遍日历。ChessboardLayout 的目标是将所有调度视图的「布局能力」抽象为单一可配置组件，让上层产品只需注入数据 + 定义业务逻辑，即可快速交付高质量调度界面。

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

Axis Modes

双轴模式设计

通过一个 axisMode 配置，组件可在两种完全不同的视觉范式间切换，覆盖市面上绝大多数调度 UI 需求。

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

Time Granularity

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

Built-in Scenarios

3 大内置场景 Demo

组件内置 3 套开箱即用的场景预设，每套包含完整的资源数据、事件数据、格子状态数据与配置项。开发者可直接运行查看效果，也可以在此基础上修改参数。

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

组件架构设计

以「零业务逻辑」为核心设计原则，所有数据模型与交互逻辑均由上层注入。组件通过 4 个核心类型完成与业务层的完整解耦。

🏗️
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

8 大配置分区

ChessboardConfig 共有 20+ 个配置项，按功能分为 8 个分区（A–H），所有项均有完整 JSDoc 说明，方便 IDE 智能提示。

§ 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 token 体系，所有颜色/圆角/间距均从 ConfigProvider 读取，无一硬编码，组件自动跟随全局主题变化。

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 文档，支持交互式配置面板演示。

ChessboardLayout · v2.0

一个组件，覆盖所有调度视图需求。设计系统团队出品，可直接发布为 npm 包集成至产品。

import { ChessboardLayout } from '@workspace/chessboard-layout'