故事016.013：修复图表数据点计算函数的 process 参数遗漏错误

元信息

史诗: 016 - mini小程序图表组件包（mini-charts）
优先级: P0 - 阻塞问题
状态: ⏳ Draft
创建日期: 2025-12-25
负责人: 开发团队

故事描述

背景

在执行故事016.004（搬迁图表数据点计算函数）时，发现了严重的参数遗漏问题。原始 u-charts.js 中，多个图表数据点计算函数包含第3个可选参数 process（动画进度，默认值1），但在搬迁时遗漏了该参数，导致运行时错误 ReferenceError: process is not defined。

错误堆栈

ReferenceError
process is not defined
Call Stack
  getPieDataPoints
    mini-ui-packages/mini-charts/dist/src/lib/charts-data/pie-charts.js:35:53
  getPieTextMaxLength
    mini-ui-packages/mini-charts/dist/src/lib/helper-functions/legend-helpers.js:194:102
  uCharts.drawCharts
    mini-ui-packages/mini-charts/dist/src/lib/draw-controllers/draw-charts.js:198:144
  new uCharts
    mini-ui-packages/mini-charts/dist/src/lib/charts/u-charts.js:215:67
  eval
    mini-ui-packages/mini-charts/dist/src/components/BaseChart.js:77:28

错误详情

受影响的函数：

getPieDataPoints(series, radius) → 应为 getPieDataPoints(series, radius, process = 1)
getRoseDataPoints(series, type, minRadius, radius) → 应为 getRoseDataPoints(series, type, minRadius, radius, process = 1)
getGaugeDataPoints(series, categories, gaugeOption) → 应为 getGaugeDataPoints(series, categories, gaugeOption, process = 1)
getGaugeArcbarDataPoints(series, arcbarOption) → 应为 getGaugeArcbarDataPoints(series, arcbarOption, process = 1)
getArcbarDataPoints(series, arcbarOption) → 应为 getArcbarDataPoints(series, arcbarOption, process = 1)

错误根因

搬迁时错误地使用了 declare const process: number; 全局声明（位于 pie-charts.ts:1-2 和 gauge-charts.ts:1-2），但这在运行时不会工作，导致 process is not defined 错误。

原始 u-charts.js 中的正确实现：

function getPieDataPoints(series, radius) {
  var process = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : 1;
  // ... 函数体使用 process 参数
}

当前错误的搬迁代码：

// pie-charts.ts:1-2
declare const process: number;  // ❌ 错误：全局声明在运行时不存在

export function getPieDataPoints(
  series: PieDataItem[],
  radius: number
): PieDataItem[] {
  // 函数体使用未定义的 process 变量
  item._proportion_ = 1 / series.length * process;  // ❌ ReferenceError
}

任务列表

任务1：修复 pie-charts.ts 中的函数签名

移除错误的 declare const process: number; 全局声明（第1-2行）
为 getPieDataPoints 添加第3个可选参数 process?: number，默认值为1
为 getRoseDataPoints 添加第5个可选参数 process?: number，默认值为1
更新 getPieDataPoints 的 JSDoc 注释，添加 process 参数说明
更新 getRoseDataPoints 的 JSDoc 注释，添加 process 参数说明
验证函数体内的 process 引用正确使用参数而非未定义的变量

参考实现：

export function getPieDataPoints(
  series: PieDataItem[],
  radius: number,
  process: number = 1
): PieDataItem[] {
  // ... 函数体
  item._proportion_ = 1 / series.length * process;  // ✅ 使用参数
}

任务2：修复 gauge-charts.ts 中的函数签名

移除错误的 declare const process: number; 全局声明（第1-2行）
为 getGaugeDataPoints 添加第4个可选参数 process?: number，默认值为1
为 getGaugeArcbarDataPoints 添加第3个可选参数 process?: number，默认值为1
为 getArcbarDataPoints 添加第3个可选参数 process?: number，默认值为1
更新所有3个函数的 JSDoc 注释，添加 process 参数说明
修复函数体内的 process 引用
- getGaugeArcbarDataPoints 中使用了局部变量 currentProcess，需要改用参数
- getArcbarDataPoints 中使用了局部变量 currentProcess，需要改用参数

参考实现：

export function getGaugeArcbarDataPoints(
  series: GaugeDataItem[],
  arcbarOption: ArcbarOption,
  process: number = 1
): GaugeDataItem[] {
  let currentProcess = process;
  if (currentProcess == 1) {
    currentProcess = 0.999999;
  }
  // ... 使用 currentProcess
}

任务3：验证所有调用点

检查所有调用这些函数的地方，确保传递正确的参数
更新 pie-renderer.ts:240 的调用，传递 chartProcess 参数
- 查看原始代码 u-charts.ts.backup:4990 确认正确的调用方式
检查 legend-helpers.ts:218 的 getPieDataPoints 调用
- 如果不需要动画，使用默认值1（不传递第3个参数）
检查 index-finders.ts:373 的 getPieDataPoints 调用
- 如果不需要动画，使用默认值1（不传递第3个参数）
检查其他可能的调用点（使用 Grep 搜索）

任务4：验证修复结果

运行类型检查 pnpm typecheck 确保无类型错误
运行构建 pnpm build 确保成功生成 .d.ts 文件
检查生成的 .d.ts 文件，确认函数签名正确
在小程序中测试饼图，确保无运行时错误
在小程序中测试玫瑰图，确保无运行时错误
在小程序中测试仪表盘，确保无运行时错误
在小程序中测试环形条，确保无运行时错误
确认动画功能正常工作（process 参数用于控制动画进度）

任务5：更新文档和示例

更新受影响函数的 JSDoc 注释，说明 process 参数的用途
在需要的地方添加代码注释，说明 process 参数控制动画进度（0-1）

验收标准

代码质量

所有受影响的函数签名已修复，包含 process?: number 可选参数
错误的 declare const process: number; 全局声明已移除
JSDoc 注释已更新，包含 process 参数说明
所有调用点已更新或验证，传递正确的参数

构建和类型检查

类型检查通过（pnpm typecheck），无类型错误
构建成功（pnpm build），生成正确的 .d.ts 文件
生成的 .d.ts 文件正确导出函数签名

功能验证

运行时错误 process is not defined 已解决
饼图在小程序中正常渲染
玫瑰图在小程序中正常渲染
仪表盘在小程序中正常渲染
环形条在小程序中正常渲染
动画功能正常工作

技术说明

process 参数的作用

用途: 控制图表动画的进度（0到1之间）
默认值: 1（表示动画完成，显示最终状态）
特殊值: 0.999999（用于 getGaugeArcbarDataPoints 和 getArcbarDataPoints，避免完全闭合时的渲染问题）
动画场景: 在动画进行中，process 从 0 逐渐增加到 1，实现平滑过渡

调用场景

静态渲染: 不传递 process 参数，使用默认值1
动画渲染: 传递 process 参数（0-1），控制动画进度
特殊处理: getGaugeArcbarDataPoints 和 getArcbarDataPoints 在 process=1 时使用 0.999999

参考文件

原始文件: docs/小程序图表库示例/u-charts小程序图表库.js
需要修复的文件:
- mini-ui-packages/mini-charts/src/lib/charts-data/pie-charts.ts
- mini-ui-packages/mini-charts/src/lib/charts-data/gauge-charts.ts
- mini-ui-packages/mini-charts/src/lib/renderers/pie-renderer.ts
- mini-ui-packages/mini-charts/src/lib/helper-functions/legend-helpers.ts
- mini-ui-packages/mini-charts/src/lib/helper-functions/index-finders.ts

依赖关系

依赖: 故事016.004（已完成的搬迁工作）
阻塞: 故事016.009（React 组件需要修复后的函数）
相关: 故事016.012（类型错误修复）

风险和缓解措施

风险

修改函数签名可能影响其他调用点
process 参数传递错误可能导致动画异常

缓解措施

使用 Grep 全面搜索所有调用点
使用可选参数 process = 1 确保向后兼容
在修复后进行完整的功能测试

完成检查清单

所有任务已完成
所有验收标准已满足
代码已审查并符合项目编码标准
运行时错误已解决
功能测试通过
文档已更新

开发者记录

实施说明

此故事需要仔细处理函数签名和调用点的更新。建议按以下顺序实施：

先修复 pie-charts.ts
再修复 gauge-charts.ts
然后搜索并更新所有调用点
最后进行类型检查和构建验证

测试策略

使用 pnpm typecheck 验证类型正确性
使用 pnpm build 验证构建成功
在小程序中测试每种图表类型
测试动画功能（如果有动画场景）

最后更新: 2025-12-25 文档版本: 1.0

016.013.story.md 8.9 KB История Исходник