Story 016.010: 创建使用示例和文档

Status

Draft

Story

作为小程序开发者, 我想要 完整的使用示例和 API 文档, 以便快速上手使用 mini-charts 包,理解各种图表组件的配置选项和使用方法。

背景

mini-charts 包已完成核心库模块化搬迁(故事 016.001-016.008)和 React 图表组件封装(故事 016.009),现在需要提供完整的文档和示例,帮助开发者快速理解和使用这个图表库。

前置故事完成状态:

✅ 故事 016.001-016.008: u-charts 核心库已完成模块化搬迁和类型定义
✅ 故事 016.009: React 图表组件封装完成,包括 BaseChart 和 5 种图表组件
✅ 所有组件类型定义完整,类型检查通过
✅ 包可以成功构建,自动生成 .d.ts 声明文件

参考资料:

docs/小程序图表库示例/使用示例.md - 原始类组件使用示例
docs/prd/epic-016-mini-charts-package.md - Epic 016 完整定义

前置故事完成状态

故事 016.001: ✅ 已完成 - 创建 mini-charts 包基础结构 故事 016.002: ✅ 已完成 - 模块化 config 和 utils 故事 016.003: ✅ 已完成 - 模块化 data-processing 函数 故事 016.004: ✅ 已完成 - 模块化 charts-data 函数 故事 016.005: ✅ 已完成 - 模块化 renderers 函数 故事 016.006: ✅ 已完成 - 搬迁核心类并完成模块化 故事 016.007: ✅ 已完成 - 搬迁遗漏的辅助函数 故事 016.008: ✅ 已完成 - 搬迁核心绘制函数完成模块化 故事 016.009: ✅ 已完成 - 创建 React 图表组件封装

Acceptance Criteria

创建 examples 目录,包含至少 3 个示例(柱状图、折线图、K线图)
创建完整的 README.md,包含所有必需章节(简介、安装、快速开始、API 文档、配置选项、常见问题)
API 文档详细,覆盖所有公共接口(组件 Props、配置选项)
配置选项说明清晰,包含示例代码
更新原使用示例文档(docs/小程序图表库示例/使用示例.md),指向新包的使用方式
示例代码使用现代 React 函数式组件,与封装的组件一致
文档和示例类型检查通过(pnpm typecheck)

Tasks / Subtasks

[ ] Task 1: 创建 examples 目录和基础示例 (AC: 1, 6)
- 1.1 创建 examples/ 目录
- 1.2 创建 examples/BasicColumnChart.tsx - 基础柱状图示例
- 1.3 创建 examples/BasicLineChart.tsx - 基础折线图示例(支持拖拽)
- 1.4 创建 examples/BasicCandleChart.tsx - 基础K线图示例
- 1.5 创建 examples/PieChartExample.tsx - 饼图示例
- 1.6 创建 examples/RadarChartExample.tsx - 雷达图示例
- 1.7 创建 examples/index.ts - 统一导出所有示例
- 1.8 所有示例使用 React 函数式组件,使用封装的图表组件
[ ] Task 2: 创建 README.md 主文档 (AC: 2, 3, 4)
- 2.1 创建 mini-ui-packages/mini-charts/README.md
- 2.2 编写「简介」章节 - 包特性、支持的图表类型
- 2.3 编写「安装」章节 - pnpm 安装命令
- 2.4 编写「快速开始」章节 - 最小化示例代码
- 2.5 编写「组件 API」章节 - 所有图表组件的 Props 接口说明
- 2.6 编写「配置选项」章节 - uCharts 配置选项详解
- 2.7 编写「常见问题」章节 - FAQ
- 2.8 编写「迁移指南」章节 - 从原始 u-charts 迁移到新组件的方式
[ ] Task 3: 创建 API 文档 (AC: 3, 4)
- 3.1 创建 docs/api/ 目录
- 3.2 创建 docs/api/BaseChart.md - BaseChart 组件 API
- 3.3 创建 docs/api/ColumnChart.md - ColumnChart 组件 API
- 3.4 创建 docs/api/LineChart.md - LineChart 组件 API
- 3.5 创建 docs/api/CandleChart.md - CandleChart 组件 API
- 3.6 创建 docs/api/PieChart.md - PieChart 组件 API
- 3.7 创建 docs/api/RadarChart.md - RadarChart 组件 API
- 3.8 每个 API 文档包含: Props 接口定义、类型说明、示例代码
[ ] Task 4: 创建高级示例 (AC: 1, 6)
- 4.1 创建 examples/MixedChartExample.tsx - 混合图表示例(如柱状图+折线图)
- 4.2 创建 examples/CustomConfigExample.tsx - 自定义配置示例(颜色、字体、动画等)
- 4.3 创建 examples/ResponsiveChartExample.tsx - 响应式图表示例
- 4.4 创建 examples/DataUpdateExample.tsx - 数据动态更新示例
[ ] Task 5: 更新 package.json 导出配置 (AC: 2)
- 5.1 更新 mini-ui-packages/mini-charts/package.json 的 exports 字段
- 5.2 添加 examples 路径导出配置
- 5.3 验证导出配置正确
[ ] Task 6: 更新原使用示例文档 (AC: 5)
- 6.1 更新 docs/小程序图表库示例/使用示例.md
- 6.2 在文档顶部添加「新版本使用方式」章节
- 6.3 提供新版本组件的使用示例代码
- 6.4 保留原始示例作为参考,标记为「旧版本」
[ ] Task 7: 验证文档和示例 (AC: 7)
- 7.1 运行类型检查验证示例代码类型正确(pnpm typecheck)
- 7.2 验证所有文档链接正确
- 7.3 验证示例代码可以复制粘贴使用
- 7.4 验证 README.md 格式规范

Dev Notes

前置故事见解

故事 016.009 完成状态总结:

✅ BaseChart 基础组件创建完成,封装 Canvas 逻辑
✅ 5 种图表组件实现完成: ColumnChart、LineChart、CandleChart、PieChart、RadarChart
✅ 所有组件支持 Props 配置,类型定义完整
✅ 组件支持触摸事件处理(tooltip 显示)
✅ 组件支持响应式尺寸计算和像素比适配
✅ 类型检查通过(pnpm typecheck)
✅ 构建成功(pnpm build),生成完整的 .d.ts 声明文件

可用的组件 API:

// src/index.ts 导出的组件
export { BaseChart } from './components/BaseChart';
export { ColumnChart } from './components/ColumnChart';
export { LineChart } from './components/LineChart';
export { CandleChart } from './components/CandleChart';
export { PieChart } from './components/PieChart';
export { RadarChart } from './components/RadarChart';

// 导出的类型定义
export type { BaseChartProps } from './components/BaseChart';
export type { ColumnChartProps } from './components/ColumnChart';
export type { LineChartProps } from './components/LineChart';
export type { CandleChartProps } from './components/CandleChart';
export type { PieChartProps } from './components/PieChart';
export type { RadarChartProps } from './components/RadarChart';

项目结构指南

来源: source-tree.md

mini-ui-packages/
└── mini-charts/              # mini-charts 包
    ├── src/
    │   ├── index.ts          # 主入口文件
    │   ├── components/       # React 图表组件 [已完成]
    │   └── lib/              # u-charts 核心库 [已完成]
    ├── examples/             # [本故事创建] 使用示例
    │   ├── BasicColumnChart.tsx      # 基础柱状图示例
    │   ├── BasicLineChart.tsx        # 基础折线图示例
    │   ├── BasicCandleChart.tsx      # 基础K线图示例
    │   ├── PieChartExample.tsx       # 饼图示例
    │   ├── RadarChartExample.tsx     # 雷达图示例
    │   ├── MixedChartExample.tsx     # 混合图表示例
    │   ├── CustomConfigExample.tsx   # 自定义配置示例
    │   ├── ResponsiveChartExample.tsx # 响应式示例
    │   ├── DataUpdateExample.tsx     # 数据更新示例
    │   └── index.ts                  # 示例导出
    ├── docs/                 # [本故事创建] API 文档
    │   └── api/
    │       ├── BaseChart.md          # BaseChart API 文档
    │       ├── ColumnChart.md        # ColumnChart API 文档
    │       ├── LineChart.md          # LineChart API 文档
    │       ├── CandleChart.md        # CandleChart API 文档
    │       ├── PieChart.md           # PieChart API 文档
    │       └── RadarChart.md         # RadarChart API 文档
    ├── README.md            # [本故事创建] 主文档
    ├── package.json
    └── tsconfig.json

组件使用示例(来自故事 016.009)

来源: 016.009 React Chart Components

柱状图组件使用

import React from 'react';
import { ColumnChart } from '@d8d/mini-charts';

const MyComponent = () => {
  const data = {
    categories: ['2018', '2019', '2020', '2021', '2022', '2023'],
    series: [{
      name: '目标值',
      data: [35, 36, 31, 33, 13, 34]
    }, {
      name: '完成量',
      data: [18, 27, 21, 24, 6, 28]
    }]
  };

  return (
    <ColumnChart
      canvasId="columnChart"
      data={data}
      dataLabel={true}
      columnType="group"
    />
  );
};

折线图组件使用

import React from 'react';
import { LineChart } from '@d8d/mini-charts';

const MyComponent = () => {
  const data = {
    categories: ['2018', '2019', '2020', '2021', '2022', '2023'],
    series: [{
      name: '成交量A',
      data: [35, 36, 31, 33, 13, 34]
    }]
  };

  return (
    <LineChart
      canvasId="lineChart"
      data={data}
      enableScroll={true}
      dataPointShape={true}
    />
  );
};

K线图组件使用

import React from 'react';
import { CandleChart } from '@d8d/mini-charts';

const MyComponent = () => {
  const data = {
    categories: ['2018', '2019', '2020', '2021', '2022', '2023'],
    series: [{
      name: '上证指数',
      data: [
        [2320.26, 2320.26, 2280.12, 2307.89],
        [2325.61, 2332.45, 2305.86, 2315.23]
      ]
    }]
  };

  return (
    <CandleChart
      canvasId="candleChart"
      data={data}
      enableScroll={true}
      showMA={[5, 10, 30]}
    />
  );
};

Props 接口定义(来自故事 016.009)

来源: 016.009 Dev Notes

BaseChartProps

export interface BaseChartProps {
  canvasId: string;              // Canvas ID
  width?: number;                // 图表宽度(可选)
  height?: number;               // 图表高度(可选)
  pixelRatio?: number;           // 像素比(可选,默认根据平台自动计算)
  categories: string[];          // X轴分类数据
  series: any[];                 // 系列数据
  config?: Record<string, any>;  // uCharts 配置对象(可选)
  onTouchStart?: (e: any) => void;
  onTouchMove?: (e: any) => void;
  onTouchEnd?: (e: any) => void;
}

ColumnChartProps

export interface ColumnChartProps extends Omit<BaseChartProps, 'canvasId'> {
  canvasId?: string;             // Canvas ID(可选,默认自动生成)
  data?: {                       // 图表数据(可选)
    categories: string[];
    series: any[];
  };
  dataLabel?: boolean;           // 是否显示数据标签(默认 true)
  columnType?: 'group' | 'stack'; // 柱状图类型(默认 'group')
  config?: Record<string, any>;  // 额外配置(可选)
}

LineChartProps

export interface LineChartProps extends Omit<BaseChartProps, 'canvasId'> {
  canvasId?: string;             // Canvas ID(可选,默认自动生成)
  data?: {                       // 图表数据(可选)
    categories: string[];
    series: any[];
  };
  dataPointShape?: boolean;      // 是否显示数据点形状(默认 true)
  enableScroll?: boolean;        // 是否启用滚动(默认 false)
  config?: Record<string, any>;  // 额外配置(可选)
}

CandleChartProps

export interface CandleChartProps extends Omit<BaseChartProps, 'canvasId'> {
  canvasId?: string;             // Canvas ID(可选,默认自动生成)
  data?: {                       // 图表数据(可选)
    categories: string[];
    series: any[];
  };
  enableScroll?: boolean;        // 是否启用滚动(默认 false)
  showMA?: number[];             // 移动平均线周期数组(如 [5, 10, 30])
  config?: Record<string, any>;  // 额外配置(可选)
}

PieChartProps

export interface PieChartProps extends Omit<BaseChartProps, 'canvasId'> {
  canvasId?: string;             // Canvas ID(可选,默认自动生成)
  data?: {                       // 图表数据(可选)
    categories: string[];
    series: any[];
  };
  pieType?: 'pie' | 'ring';      // 饼图类型(默认 'pie')
  dataLabel?: boolean;           // 是否显示数据标签(默认 true)
  config?: Record<string, any>;  // 额外配置(可选)
}

RadarChartProps

export interface RadarChartProps extends Omit<BaseChartProps, 'canvasId'> {
  canvasId?: string;             // Canvas ID(可选,默认自动生成)
  data?: {                       // 图表数据(可选)
    categories: string[];
    series: any[];
  };
  dataPointShape?: boolean;      // 是否显示数据点形状(默认 true)
  config?: Record<string, any>;  // 额外配置(可选)
}

技术栈要求

来源: mini-charts/package.json

React: 18.0.0（mini 包使用 React 18，不是 React 19）
Taro: 4.1.4（包括 @tarojs/components, @tarojs/react, @tarojs/taro）
TypeScript: 5.4.5
Node.js: 20.18.3（运行时环境）
包管理器: pnpm workspace

TypeScript 配置规范

来源: ui-package-standards.md

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["DOM", "DOM.Iterable", "ES2020"],
    "module": "ESNext",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true
  }
}

本故事重要: 示例代码必须满足 TypeScript 严格模式,类型检查通过。

文档编写规范

README.md 结构要求:

# @d8d/mini-charts

## 简介
- 包特性描述
- 支持的图表类型
- 技术特性

## 安装
\`\`\`bash
pnpm add @d8d/mini-charts
\`\`\`

## 快速开始
\`\`\`typescript
import { ColumnChart } from '@d8d/mini-charts';
// 最小化示例
\`\`\`

## 组件 API
- BaseChart
- ColumnChart
- LineChart
- CandleChart
- PieChart
- RadarChart

## 配置选项
- 通用配置
- 各图表类型专属配置

## 常见问题
- FAQ列表

## 迁移指南
- 从原始 u-charts 迁移

## 相关链接
- u-charts 官方文档

API 文档结构要求:

# [ComponentName] API

## 概述
组件简要描述

## Props 接口
\`\`\`typescript
export interface ComponentNameProps {
  // Props 定义
}
\`\`\`

## Props 说明
| Prop | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| ... | ... | ... | ... |

## 示例代码
\`\`\`typescript
// 完整示例
\`\`\`

## 相关文档
- 链接到其他相关组件

package.json 导出配置规范

来源: ui-package-standards.md

{
  "exports": {
    ".": {
      "types": "./src/index.ts",
      "import": "./src/index.ts",
      "require": "./src/index.ts"
    },
    "./components": {
      "types": "./src/components/index.ts",
      "import": "./src/components/index.ts",
      "require": "./src/components/index.ts"
    }
  }
}

本故事: 需要添加 examples 导出配置。

编码标准

来源: coding-standards.md

代码风格: TypeScript 严格模式,一致的缩进和命名
示例代码: 使用 React 函数式组件,与封装的组件一致
注释规范: 为复杂配置添加中文注释说明
文档格式: 使用 Markdown 格式,代码块指定语言类型

测试要求

来源: testing-strategy.md

本故事: 文档和示例代码需要通过类型检查,验证其正确性。

# 类型检查示例代码
pnpm typecheck

原始使用示例分析

来源: docs/小程序图表库示例/使用示例.md

原始使用方式(类组件):

使用 Component 类组件
手动管理 Canvas 上下文 (Taro.createCanvasContext)
手动计算响应式尺寸
手动处理触摸事件
使用原始 uCharts 类

新使用方式(函数式组件):

使用现代 React 函数式组件
使用封装的图表组件,无需手动管理 Canvas
组件内部自动处理响应式尺寸
组件内部自动处理触摸事件
类型安全的 Props 接口

文件位置规范

新增文件位置:

示例目录: mini-ui-packages/mini-charts/examples/
API 文档: mini-ui-packages/mini-charts/docs/api/
主文档: mini-ui-packages/mini-charts/README.md

修改文件:

mini-ui-packages/mini-charts/package.json - 添加 examples 导出配置
docs/小程序图表库示例/使用示例.md - 添加新版本使用方式

技术约束

React版本: 必须使用 React 18 函数式组件
Taro版本: 使用 @tarojs/taro 4.1.4 API
类型安全: 示例代码必须通过类型检查
文档格式: 使用 Markdown 格式
代码示例: 所有示例代码必须可以复制粘贴使用
中文文档: 所有文档使用中文编写

验证标准

完成本故事后,应该满足:

✅ examples/ 目录下至少有 3 个基础示例和 3 个高级示例
✅ README.md 文档完整,包含所有必需章节
✅ docs/api/ 目录下每个组件都有 API 文档
✅ API 文档详细,覆盖所有公共接口
✅ 配置选项说明清晰,包含示例
✅ 原使用示例文档已更新,添加新版本使用方式
✅ 运行 pnpm typecheck 无类型错误
✅ 示例代码可以直接复制使用

不包含在本故事中的工作

以下工作不在本故事范围内:

❌ 创建完整的测试套件(故事 016.011)
❌ 在实际小程序页面中集成使用示例
❌ 创建在线文档网站
❌ 性能优化和基准测试

Change Log

Date	Version	Description	Author
2025-12-24	1.0	创建故事文档	Bob (Scrum Master)

Dev Agent Record

此部分由开发代理在实施过程中填写

Agent Model Used

待填写

Debug Log References

待填写

Completion Notes List

待填写

File List

待填写

QA Results

此部分由 QA 代理在审查完成后填写

016.010.examples-and-docs.md 18 KB История Исходник