epic-016-mini-charts-package.md 10 KB
史诗016 - mini小程序图表组件包（mini-charts）
史诗目标
将 docs/小程序图表库示例/ 目录下的 u-charts 图表库（约7700行代码）迁移为独立的 mini-ui-packages 共享包 mini-charts，为 Taro 小程序提供完整的图表解决方案，支持柱状图、折线图、K线图等多种图表类型。
史诗描述
现有系统上下文
当前相关功能：
- u-charts 图表库：位于
docs/小程序图表库示例/u-charts小程序图表库.js，是一个高性能跨平台图表库 - 支持平台：H5、APP、小程序（微信/支付宝/百度/头条/QQ/360/快手）、Vue、Taro等支持canvas的框架平台
- 示例代码：
docs/小程序图表库示例/使用示例.md提供了完整的 React + Taro 使用示例 - 版本信息：v2.5.0-20230101
技术特性：
- 支持多种图表类型：柱状图(column)、折线图(line)、K线图(candle)、饼图、雷达图等
- 支持Canvas绘制，高性能渲染
- 支持触摸交互：tooltip显示、拖拽滚动
- 支持数据标签、图例、动画效果
- 高度可配置：颜色、字体、网格、坐标轴等
- 响应式设计，支持多种屏幕尺寸和像素比
集成点：
- Taro Canvas API
- React 18组件系统
- 小程序平台适配（微信小程序为主）
- 与现有 mini-ui-packages 包结构保持一致
- 与现有测试框架（Jest）集成
当前架构分析：
- 图表库未模块化：u-charts 库文件位于文档目录下，未形成可复用的包
- 缺少类型定义：原库为纯JavaScript，缺少TypeScript类型支持
- 缺少React组件封装：示例代码展示的是类组件使用方式，需要现代函数式组件封装
- 缺少测试：没有针对图表组件的测试套件
- 缺少文档：只有使用示例，缺少完整的API文档
增强详情
改造范围： 本次史诗将完成以下工作：
阶段1：创建 mini-charts 包基础结构（故事016.001）
- 创建新的包
mini-ui-packages/mini-charts - 配置 package.json，依赖 Taro 相关包
- 设置 TypeScript 配置和类型定义
- 配置构建和测试脚本
- 迁移 u-charts 核心库文件
阶段2：添加 TypeScript 类型定义（故事016.002）
- 为 u-charts 库添加完整的 TypeScript 类型定义
- 定义图表配置接口（ChartConfig、SeriesConfig、AxisConfig等）
- 定义图表类型枚举（ChartType）
- 导出类型供使用者使用
阶段3：创建 React 组件封装（故事016.003）
- 创建现代函数式图表组件：
- ColumnChart（柱状图）
- LineChart（折线图）
- CandleChart（K线图）
- PieChart（饼图）
- RadarChart（雷达图）
- 使用 Taro Canvas API 封装底层绘图逻辑
- 支持触摸事件处理（tooltip、拖拽）
- 支持响应式尺寸计算
阶段4：创建使用示例和文档（故事016.004）
- 在包内创建 examples 目录
- 提供完整的示例代码
- 创建 API 文档
- 更新使用示例.md
阶段5：创建测试套件（故事016.005）
- 设置 Jest 测试环境
- 创建图表组件单元测试
- 创建 Canvas mock 用于测试
- 验证组件渲染和交互
迁移策略：
- 保留原始逻辑：保持 u-charts 核心绘制逻辑不变
- 渐进式封装：先迁移核心库，再添加类型定义，最后创建 React 组件
- 向后兼容：提供直接使用 u-charts 类的接口
- 测试驱动：为每个组件编写测试
成功标准：
mini-charts包创建成功，可通过 workspace 引用- u-charts 核心库成功迁移，功能完整
- TypeScript 类型定义完整，无 any 类型
- 提供至少5种常用图表组件（柱状图、折线图、K线图、饼图、雷达图）
- 组件可以独立测试（类型检查和 Jest 测试通过）
- 提供完整的示例和文档
- 可以被 mini 项目或其他 mini-ui-packages 引用
故事列表
故事016-001：创建 mini-charts 包基础结构
背景： u-charts 图表库目前位于文档目录下，需要迁移为独立的共享包，以便在多个小程序项目中复用。
任务列表：
- 创建新的包
mini-ui-packages/mini-charts- 配置 package.json，依赖 Taro 相关包
- 设置 TypeScript 配置（tsconfig.json）
- 配置构建和测试脚本
- 迁移 u-charts 核心库文件：
- 将
docs/小程序图表库示例/u-charts小程序图表库.js迁移到src/lib/u-charts.ts - 保持原始逻辑不变
- 将文件转换为 TypeScript 格式（添加基础类型）
- 将
- 创建包的导出配置：
- 建立 src/index.ts 主入口
- 导出 u-charts 核心类
- 配置 package.json 的 exports 字段
验收标准：
-
mini-charts包目录结构创建完成 - package.json 配置正确，包含所有必需依赖
- tsconfig.json 配置正确
- u-charts 核心库迁移成功，无语法错误
- 包可以成功构建（tsc 编译通过）
- 类型检查通过（pnpm typecheck）
故事016-002：添加 TypeScript 类型定义
背景： u-charts 原库为纯JavaScript，缺少类型支持。需要添加完整的 TypeScript 类型定义，提高开发体验和代码安全性。
任务列表：
- 分析 u-charts 库的配置选项
- 阅读源代码，理解各种配置参数
- 参考使用示例.md 中的配置
- 识别所有公共 API
- 定义 TypeScript 接口：
- ChartConfig：图表总配置接口
- ChartType：图表类型枚举（'column' | 'line' | 'candle' | 'pie' | 'radar' 等）
- SeriesConfig：数据系列配置
- AxisConfig：坐标轴配置（X轴、Y轴）
- ExtraConfig：各种图表的额外配置
- ColorConfig：颜色配置
- 为 u-charts 类添加类型定义
- 导出所有类型供使用者使用
验收标准：
- 所有配置选项都有对应的类型定义
- ChartType 枚举包含所有支持的图表类型
- 类型定义完整，无 any 类型（除非必要）
- 类型导出正确，可以被使用者导入
- 类型检查通过，无类型错误
故事016-003：创建 React 图表组件封装
背景： u-charts 原库需要手动管理 Canvas 上下文和事件处理。需要创建现代 React 函数式组件，简化使用方式。
任务列表：
- 创建基础图表组件 BaseChart：
- 封装 Canvas 创建和销毁逻辑
- 处理响应式尺寸计算
- 处理像素比适配
- 封装事件处理（触摸、点击）
- 创建具体图表组件：
- ColumnChart（柱状图）
- LineChart（折线图）
- CandleChart（K线图）
- PieChart（饼图）
- RadarChart（雷达图）
- 每个组件包含：
- Props 接口定义
- 默认配置
- Canvas 绘制逻辑
- 事件处理（tooltip、拖拽等）
- 从
docs/小程序图表库示例/使用示例.md迁移示例代码作为参考
验收标准：
- BaseChart 基础组件创建完成
- 至少5种图表组件实现完成
- 组件支持 Props 配置
- 组件支持触摸事件（tooltip）
- 组件支持响应式尺寸
- 类型定义完整，无类型错误
故事016-004：创建使用示例和文档
背景： 需要提供完整的使用示例和 API 文档，帮助开发者快速上手使用 mini-charts 包。
任务列表：
- 创建 examples 目录：
- 迁移并更新
docs/小程序图表库示例/使用示例.md中的示例 - 为每种图表类型创建独立示例
- 创建复杂场景示例（混合图表、多轴图表等）
- 迁移并更新
- 创建 README.md：
- 包简介和特性
- 安装说明
- 快速开始指南
- API 文档
- 配置选项说明
- 常见问题解答
- 更新原使用示例文档，指向新包的使用方式
验收标准：
- examples 目录创建完成，包含至少3个示例
- README.md 文档完整，包含所有必需章节
- API 文档详细，覆盖所有公共接口
- 配置选项说明清晰，包含示例
- 原使用示例文档已更新
故事016-005：创建测试套件
背景： 需要为图表组件创建完整的测试套件，确保组件质量和稳定性。
任务列表：
- 设置 Jest 测试环境：
- 配置 jest.config.js
- 创建 Taro 和 Canvas 的 mock
- 创建工具函数：
- createMockCanvasContext：创建模拟 Canvas 上下文
- waitForChartRender：等待图表渲染完成
- 编写组件测试：
- 测试组件渲染
- 测试 Props 传递
- 测试事件处理
- 测试响应式尺寸
- 编写集成测试：
- 测试图表数据更新
- 测试图表交互
验收标准：
- Jest 测试环境配置完成
- Canvas mock 创建完成
- 每个图表组件都有单元测试
- 测试覆盖率达到 60% 以上
- 所有测试通过
兼容性要求
- 保持 u-charts 原库功能完整性
- 支持微信小程序平台
- 支持 Taro 4.1.4 框架
- 支持 React 18
- 向后兼容，支持直接使用 u-charts 类
风险缓解
- 主要风险：u-charts 库文件较大（约7700行），迁移过程中可能遗漏功能
- 缓解措施：保留原始文件，迁移后进行功能对比测试
- 回滚计划：如果迁移导致问题，可以从文档目录重新使用原文件
- 类型定义风险：原库没有类型，可能存在类型定义不准确的问题
- 缓解措施：先添加基础类型，然后逐步完善，使用 any 作为过渡
完成定义
- 所有故事完成，验收标准满足
- 类型检查通过，无 TypeScript 错误
- 所有测试通过，包括单元测试和集成测试
- 代码审查通过，符合项目编码标准
- 文档完整，包含使用示例和 API 文档
- 包可以被其他 mini-ui-packages 或 mini 项目引用
附件
- u-charts 官方网站
- 开源地址
- uni-app插件市场地址
- 本项目中的 u-charts 文件：docs/小程序图表库示例/u-charts小程序图表库.js
- 本项目中的使用示例：docs/小程序图表库示例/使用示例.md