# <!-- Powered by BMAD™ Core -->

# 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

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

```typescript
// 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](../../architecture/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](016.009.react-chart-components.md)

#### 柱状图组件使用

```typescript
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"
    />
  );
};
```

#### 折线图组件使用

```typescript
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线图组件使用

```typescript
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](016.009.react-chart-components.md#dev-notes)

#### BaseChartProps

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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](../../mini-ui-packages/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](../../architecture/ui-package-standards.md#typescript配置)

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

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

### 文档编写规范

**README.md 结构要求**:

```markdown
# @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 文档结构要求**:

```markdown
# [ComponentName] API

## 概述
组件简要描述

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

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

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

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

### package.json 导出配置规范

**来源**: [ui-package-standards.md](../../architecture/ui-package-standards.md#packagejson配置)

```json
{
  "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](../../architecture/coding-standards.md)

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

### 测试要求

**来源**: [testing-strategy.md](../../architecture/testing-strategy.md)

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

```bash
# 类型检查示例代码
pnpm typecheck
```

### 原始使用示例分析

**来源**: [docs/小程序图表库示例/使用示例.md](../../小程序图表库示例/使用示例.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` - 添加新版本使用方式

### 技术约束

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

### 验证标准

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

### 不包含在本故事中的工作

以下工作**不在**本故事范围内:
- ❌ 创建完整的测试套件(故事 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 代理在审查完成后填写*