canvasground

基于 Canvas 的国际象棋棋盘库，对标 chessground（DOM 实现），同时适配浏览器、微信小程序、抖音小程序三个平台。

特性

• 纯 Canvas 渲染 — 无 DOM 依赖，性能一致，易于跨平台
• 三端适配 — 浏览器、微信小程序、抖音小程序共用同一套核心逻辑
• 完整交互 — 拖拽、点击移动、预移（Premove）、右键绘制箭头/圆圈
• 动画系统 — 棋子平滑移动、淡出消失、原子象棋爆炸特效
• 丰富高亮 — 最后移动、将军、选中格、合法目标点、自定义格子样式
• 坐标轴 — 可配置显示方式
• FEN 支持 — 导入与导出
• TypeScript — 完整类型定义

项目结构

canvasground/
├── src/
│   ├── index.ts              # 入口，工厂函数 Canvasground()
│   ├── types.ts              # 所有类型定义
│   ├── state.ts              # 状态结构 + defaults()
│   ├── api.ts                # 公开 API 实现
│   ├── board.ts              # 棋盘逻辑（移动/选中/易位）
│   ├── fen.ts                # FEN 解析与生成
│   ├── premove.ts            # 预移合法性校验
│   ├── render/               # Canvas 绘制层（格子、棋子、高亮、动画…）
│   ├── interaction/          # 事件、拖拽、绘图交互
│   └── platform/             # 平台适配器（browser / wechat / douyin）
├── tests/
│   └── unit/                 # 单元测试（vitest）
└── public/
    └── pieces/cburnett/      # 12 张棋子 SVG 图片

完整 API 方法

| 方法 | 说明 | |------|------| | set(config) | 增量更新配置 | | state | 只读内部状态 | | getFen() | 获取当前 FEN | | toggleOrientation() | 翻转棋盘 | | move(orig, dest) | 程序化移动棋子 | | setPieces(diff) | 批量增删棋子 | | selectSquare(key) | 程序化选中格子 | | newPiece(piece, key) | 放入新棋子 | | playPremove() | 执行预移 | | cancelPremove() | 取消预移 | | cancelMove() | 取消当前移动 | | stop() | 停止所有操作 | | explode(keys) | 触发爆炸特效 | | setShapes(shapes) | 设置用户绘制的形状 | | setAutoShapes(shapes) | 设置程序控制的形状 | | getKeyAtPos(pos) | 像素坐标转棋盘格名 | | redrawAll() | 强制全量重绘 | | dragNewPiece(piece, event) | 从外部拖入新棋子 | | destroy() | 销毁实例，释放资源 |

环境要求

• Node.js >= 24.0.0

快速开始

# 安装依赖
npm install

# 类型检查
npm run typecheck

# 构建产物
npm run build

# 运行所有单元测试
npm run test

# 监视模式运行测试
npm run test:watch

# 运行单个测试文件
npx vitest run tests/unit/fen.test.ts

# Lint
npm run lint