Mini-Graph-Card中柱状图数据聚合问题的技术解析

问题背景

在使用Home Assistant的mini-graph-card插件时，用户遇到了一个关于数据展示不一致的问题。当使用utility meter类型的雨量传感器数据时，history-graph卡片和mini-graph-card卡片对相同数据的展示结果存在显著差异。

现象描述

用户配置了两个卡片：

1. 标准的history-graph卡片，正确显示了超过80mm的降雨量
2. mini-graph-card卡片，配置为柱状图模式，却只显示了55mm的降雨量

雨量传感器的工作原理是：通过翻斗式雨量计记录翻转次数（每次翻转对应0.5mm降雨），然后通过模板传感器转换为毫米单位，最后通过utility meter按日汇总。

技术分析

数据聚合机制

mini-graph-card默认使用"mean"(平均值)作为聚合函数，而utility meter类型的传感器通常记录的是累计值。这种不匹配导致了数据显示异常。

对于雨量数据这类累计型指标，正确的聚合方式应该是：

• 对于原始数据：使用"max"函数获取峰值
• 对于已聚合数据：使用"last"函数获取最终值

配置建议

正确的mini-graph-card配置应包含以下关键参数：

type: custom:mini-graph-card
entities:
  - entity: sensor.daily_rain
name: Daily rain
hours_to_show: 168
group_by: date
aggregate_func: max  # 关键参数
show:
  graph: bar

深入理解

1. group_by参数：当设置为"date"时，卡片会按天聚合数据，这正是用户期望的每日柱状图效果。

2. aggregate_func参数：这个参数决定了如何从原始数据点计算聚合值。对于雨量数据：

   • "max"：取时间段内的最大值（适合原始累计数据）
   • "last"：取最后一个值（适合已聚合数据）
   • "mean"：计算平均值（默认值，不适合累计数据）

3. points_per_hour：对于高频更新的传感器，需要适当增加此值以确保数据精度。

解决方案

1. 明确数据类型：首先确认传感器提供的是原始累计数据还是已聚合数据。

2. 选择合适的聚合函数：

   • 原始累计数据 → 使用"max"
   • 已聚合数据 → 使用"last"

3. 验证配置：建议先使用最简单的配置与history-graph对比，然后逐步添加功能参数。

最佳实践

1. 对于气象数据这类累计型指标，强烈建议明确指定aggregate_func参数。

2. 在开发自定义卡片时，考虑为不同类型的数据（累计型、瞬时型、状态型）提供不同的默认聚合策略。

3. 调试时可以先使用折线图模式，确认数据点是否正确，再切换到柱状图模式。

通过正确理解数据特性和卡片配置参数，可以确保mini-graph-card准确展示各类传感器数据，特别是像雨量这样的累计型指标。