c49f66757e
Some checks failed
Docker Build & Deploy / Build Docker Image (push) Waiting to run
Docker Build & Deploy / Deploy to Production (push) Has been cancelled
Docker Build & Deploy / Cleanup Dangling Images (push) Has been cancelled
Docker Build & Deploy / WeChat Notification (push) Has been cancelled
3.3 KiB
3.3 KiB
Context
EmailBill 项目已从 ECharts 迁移到 Chart.js 作为图表库。在迁移过程中，图表文本显示出现了乱码问题，特别是在显示中文标签、Tooltip 和中心文本时。这可能是由于：
- Chart.js 默认字体配置不支持中文
- Tooltip 回调函数返回的字符串编码问题
- 主题切换时字体颜色对比度不足
当前图表组件位于 Web/src/components/Charts/，使用 BaseChart.vue 作为统一包装组件。
Goals / Non-Goals
Goals:
- 修复所有图表（饼图、折线图、仪表盘）的中文乱码问题
- 确保图表文本在明/暗主题下都清晰可读
- 统一字体配置，支持跨平台中文显示
- 修复 Tooltip 和 Label 的文本格式化问题
Non-Goals:
- 不修改图表的数据结构或业务逻辑
- 不添加新的图表类型
- 不进行 UI 样式的大幅度调整（仅修复文本显示问题）
Decisions
Decision 1: 字体配置方案
选择: 在 useChartTheme.ts 中统一配置 Chart.js 字体选项
理由:
- Chart.js 支持全局字体配置，通过
defaults.font.family可以一次性设置所有图表的字体 - 使用系统字体栈确保跨平台兼容性：
'PingFang SC', 'Microsoft YaHei', 'Helvetica Neue', Arial, sans-serif - 避免在每个组件中重复配置
替代方案考虑:
- 在每个图表组件中单独配置字体 → 重复代码，维护困难
- 使用 WebFont 加载自定义字体 → 增加外部依赖，加载时间不可控
Decision 2: Tooltip 格式化修复方案
选择: 修复 callbacks.label 和 callbacks.title 回调函数，确保返回正确的字符串
理由:
- Chart.js 的 Tooltip 回调函数必须返回字符串，不能返回对象或其他类型
- 使用模板字符串确保正确的字符串拼接
- 添加空值检查防止 undefined 导致的乱码
代码示例:
tooltip: {
callbacks: {
label: (context) => {
const value = context.parsed.y || context.parsed
return `¥${value.toFixed(2)}`
}
}
}
Decision 3: 中心文本显示方案
选择: 继续使用 CSS 绝对定位的覆盖层显示中心文本
理由:
- Chart.js 本身不支持在 Doughnut 图表中心直接渲染文本
- CSS 覆盖层方式简单可靠，易于控制字体样式
- 确保覆盖层使用正确的字体族和颜色
实现要点:
- 覆盖层容器设置
font-family继承自主题配置 - 使用
var(--van-text-color)确保主题适配 - 添加
white-space: nowrap防止文本换行导致错位
Risks / Trade-offs
| Risk | Mitigation |
|---|---|
| 某些旧版浏览器可能不支持系统字体栈 | 提供后备字体（Arial, sans-serif）确保基本可读性 |
| 暗色模式下文本颜色对比度不足 | 使用 Vant 主题变量确保颜色适配 |
| 字体文件过大影响加载性能 | 使用系统字体，不加载外部字体文件 |
| 修改全局配置可能影响其他组件 | 在 useChartTheme 中集中管理，便于回滚 |
Migration Plan
- 阶段 1: 修改
useChartTheme.ts添加全局字体配置 - 阶段 2: 检查并修复各图表组件的 Tooltip 回调函数
- 阶段 3: 验证所有图表页面的文本显示
- 阶段 4: 在明/暗主题下分别测试
Rollback Strategy: 所有修改都是配置层面的，可以通过回滚 Git 提交快速恢复。