ha-graphs-visualization

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Works with Home Assistant native cards, HACS custom cards, and YAML configurations.

支持Home Assistant原生卡片、HACS自定义卡片及YAML配置。

Home Assistant Graphs and Visualization

Home Assistant 图表与可视化

Create informative graphs and charts for sensor data visualization in Home Assistant dashboards.

为Home Assistant控制面板创建信息丰富的图表，用于传感器数据可视化。

When to Use This Skill

何时使用该技能

Use this skill when you need to:

Display sensor data over time with history-graph for recent data (hours/days)
Create long-term trend analysis with statistics-graph for weeks/months
Build compact sparkline graphs with mini-graph-card for dashboard space efficiency
Generate publication-quality charts with ApexCharts for multi-sensor comparisons
Add dual Y-axis graphs for temperature + humidity or similar combinations
Troubleshoot ApexCharts span.end errors with validated configurations

Do NOT use when:

You only need current sensor values without history (use gauge or entity cards)
Building real-time monitoring without historical context (use current state displays)
You haven't installed required HACS cards (mini-graph-card or apexcharts-card)

在以下场景中使用本技能：

使用history-graph展示近期（数小时/数天）的传感器时序数据
使用statistics-graph进行周/月级别的长期趋势分析
使用mini-graph-card构建紧凑的迷你图表，提升控制面板空间利用率
使用ApexCharts生成具备出版级质量的图表，用于多传感器对比
添加双Y轴图表，用于展示温度+湿度或类似组合数据
通过验证后的配置排查ApexCharts的span.end错误

Quick Start

何时不使用该技能

This skill covers four main graphing solutions:

History Graph (native): Simple sensor history with automatic long-term statistics
Statistics Graph (native): Long-term trend analysis with aggregations
Mini-Graph-Card (HACS): Popular, lightweight graphs with customization
ApexCharts Card (HACS): Advanced publication-quality charts with annotations

在以下场景中请勿使用：

仅需查看传感器当前值无需历史数据时（使用仪表盘或实体卡片）
构建无历史上下文的实时监控时（使用当前状态显示组件）
未安装所需HACS卡片（mini-graph-card或apexcharts-card）时

Basic Examples

快速入门

History Graph (Native):

yaml

type: history-graph
entities:
  - entity: sensor.temperature
    name: Living Room
  - entity: sensor.humidity
hours_to_show: 24

ApexCharts (HACS) - VALIDATED CONFIG:

CRITICAL: The

span.end

field must be one of: "minute", "hour", "day", "week", "month", "year", "isoWeek"

yaml

type: custom:apexcharts-card
header:
  show: true
  title: 24 Hour History
  show_states: true
graph_span: 24h
span:
  end: hour  # REQUIRED: minute/hour/day/week/month/year/isoWeek
yaxis:
  - min: 0
    max: 50
    decimals: 1
apex_config:
  chart:
    height: 200
  xaxis:
    type: datetime
    labels:
      datetimeFormatter:
        hour: "HH:mm"
  legend:
    show: true
series:
  - entity: sensor.temperature
    name: Temperature
    color: "#e74c3c"
    stroke_width: 2

Common ApexCharts Errors:

❌ WRONG:
```
"span": {"end": "now"}
```
→ Causes parsing error
✅ CORRECT:
```
"span": {"end": "hour"}
```
→ Valid value

本技能涵盖四种主要图表解决方案：

History Graph（原生）：具备自动长期统计功能的简单传感器历史数据展示
Statistics Graph（原生）：支持数据聚合的长期趋势分析
Mini-Graph-Card（HACS）：广受欢迎的轻量级可自定义图表
ApexCharts Card（HACS）：具备注释功能的出版级高级图表

Usage

基础示例

Follow these steps to create Home Assistant graphs:

Select graph type based on data (native vs HACS)
Configure time ranges appropriate for data frequency
Add multiple entities for comparisons
Set y-axis bounds for proper scaling
Apply styling for readability

History Graph（原生）：

yaml

type: history-graph
entities:
  - entity: sensor.temperature
    name: Living Room
  - entity: sensor.humidity
hours_to_show: 24

ApexCharts（HACS）- 验证通过的配置：

重要提示：

span.end

字段必须为以下值之一："minute"、"hour"、"day"、"week"、"month"、"year"、"isoWeek"

yaml

type: custom:apexcharts-card
header:
  show: true
  title: 24 Hour History
  show_states: true
graph_span: 24h
span:
  end: hour  # REQUIRED: minute/hour/day/week/month/year/isoWeek
yaxis:
  - min: 0
    max: 50
    decimals: 1
apex_config:
  chart:
    height: 200
  xaxis:
    type: datetime
    labels:
      datetimeFormatter:
        hour: "HH:mm"
  legend:
    show: true
series:
  - entity: sensor.temperature
    name: Temperature
    color: "#e74c3c"
    stroke_width: 2

常见ApexCharts错误：

❌ 错误写法：
```
"span": {"end": "now"}
```
→ 会导致解析错误
✅ 正确写法：
```
"span": {"end": "hour"}
```
→ 有效值

Graph Selection Decision Tree

使用步骤

START
│
├─ Need simple sensor history (last 24-48h)?
│  └─ YES → Use history-graph (native)
│
├─ Need long-term trends (weeks/months)?
│  └─ YES → Use statistics-graph (native)
│
├─ Need minimalist design with moderate customization?
│  └─ YES → Use mini-graph-card (HACS)
│
└─ Need advanced features (annotations, comparisons, multi-axis)?
   └─ YES → Use apexcharts-card (HACS)

按照以下步骤创建Home Assistant图表：

选择图表类型：根据数据需求选择原生或HACS图表
配置时间范围：匹配数据频率设置合适的时间范围
添加多个实体：用于数据对比
设置Y轴范围：确保数据展示比例合适
应用样式设置：提升可读性

Comparison Matrix

图表选择决策树

Feature	History Graph	Statistics Graph	Mini-Graph-Card	ApexCharts
Type	Native	Native	HACS	HACS
UI Editor	✅ Full	✅ Full	❌ YAML only	❌ YAML only
Performance	⚡ Fast	⚡ Fast	⚡ Fast	⚠️ Moderate
Customization	🔹 Basic	🔹 Basic	🔸 Good	🔶 Extensive
Multiple Entities	✅ Yes	✅ Yes	✅ Yes	✅ Yes
Chart Types	Line	Line/Bar	Line/Bar	Line/Bar/Area/Column
Time Range	Hours	Calendar periods	Hours	Flexible spans
Statistics	Auto	Built-in	Manual	Manual
Best For	Quick history	Long-term trends	Clean design	Power users

开始
│
├─ 需要简单的传感器历史数据（最近24-48小时）？
│  └─ 是 → 使用history-graph（原生）
│
├─ 需要长期趋势分析（周/月）？
│  └─ 是 → 使用statistics-graph（原生）
│
├─ 需要极简设计并支持中度自定义？
│  └─ 是 → 使用mini-graph-card（HACS）
│
└─ 需要高级功能（注释、多对比、多轴）？
   └─ 是 → 使用apexcharts-card（HACS）

History Graph Card (Native)

功能对比矩阵

Best for: Simple sensor history visualization (recent data)

功能	History Graph	Statistics Graph	Mini-Graph-Card	ApexCharts
类型	原生	原生	HACS	HACS
UI编辑器	✅ 完整支持	✅ 完整支持	❌ 仅支持YAML	❌ 仅支持YAML
性能	⚡ 快速	⚡ 快速	⚡ 快速	⚠️ 中等
自定义程度	🔹 基础	🔹 基础	🔸 良好	🔶 丰富
多实体支持	✅ 是	✅ 是	✅ 是	✅ 是
图表类型	折线图	折线图/柱状图	折线图/柱状图	折线图/柱状图/面积图/柱形图
时间范围	小时级	日历周期	小时级	灵活时间跨度
统计功能	自动	内置	手动	手动
最佳适用场景	快速查看历史数据	长期趋势分析	简洁设计	高级用户

Basic Configuration

History Graph卡片（原生）

yaml

type: history-graph
entities:
  - entity: sensor.temperature_living_room
    name: Living Room
  - entity: sensor.temperature_bedroom
    name: Bedroom
hours_to_show: 24
refresh_interval: 0  # Default: auto-refresh

最佳适用场景： 简单的传感器历史数据可视化（近期数据）

Key Features

基础配置

Displays sensor history from recorder database
Automatically switches to long-term statistics for older data
Bold line = recorder data, thin line = statistics
If
```
hours_to_show
```
> recorder retention: uses long-term statistics

Performance Note: History graphs are very fast because they use HA's built-in recorder data.

yaml

type: history-graph
entities:
  - entity: sensor.temperature_living_room
    name: Living Room
  - entity: sensor.temperature_bedroom
    name: Bedroom
hours_to_show: 24
refresh_interval: 0  # 默认：自动刷新

Statistics Graph Card (Native)

核心功能

Best for: Long-term trend analysis (weeks, months, years)

展示记录器数据库中的传感器历史数据
对于较旧数据自动切换为长期统计数据
粗线 = 记录器数据，细线 = 统计数据
如果
```
hours_to_show
```
超过记录器保留期限：使用长期统计数据

性能说明： History图表速度极快，因为它使用HA内置的记录器数据。

Basic Configuration

Statistics Graph卡片（原生）

yaml

type: statistics-graph
entities:
  - sensor.energy_daily
stat_types:
  - mean
  - min
  - max
period:
  calendar:
    period: month
chart_type: line

See

references/reference.md

for stat types and period options.

最佳适用场景： 长期趋势分析（周、月、年）

Mini-Graph-Card (HACS)

基础配置

Installation: HACS → Frontend → Search "mini-graph-card"

Best for: Minimalist design, lightweight, moderate customization

yaml

type: statistics-graph
entities:
  - sensor.energy_daily
stat_types:
  - mean
  - min
  - max
period:
  calendar:
    period: month
chart_type: line

查看

references/reference.md

获取统计类型和周期选项。

Basic Temperature Graph

Mini-Graph-Card（HACS）

yaml

type: custom:mini-graph-card
entities:
  - sensor.temperature_bedroom
  - sensor.temperature_living_room
name: Temperature Comparison
hours_to_show: 24
points_per_hour: 2
line_width: 2
font_size: 75

安装方法： HACS → 前端 → 搜索"mini-graph-card"

最佳适用场景： 极简设计、轻量级、中度自定义

Multiple Entities with Colors

基础温度图表

yaml

type: custom:mini-graph-card
entities:
  - entity: sensor.temperature
    name: Temp
    color: '#e74c3c'
  - entity: sensor.humidity
    name: Humidity
    color: '#3498db'
    y_axis: secondary
show:
  labels: true
  legend: true
  name: true
  state: true

See

references/reference.md

for complete configuration options and

examples/examples.md

for more patterns.

yaml

type: custom:mini-graph-card
entities:
  - sensor.temperature_bedroom
  - sensor.temperature_living_room
name: Temperature Comparison
hours_to_show: 24
points_per_hour: 2
line_width: 2
font_size: 75

ApexCharts Card (HACS) - VALIDATED CONFIGURATIONS

多实体带颜色配置

Installation: HACS → Frontend → Search "apexcharts-card"

Best for: Advanced visualizations, publication-quality charts, complex comparisons

yaml

type: custom:mini-graph-card
entities:
  - entity: sensor.temperature
    name: Temp
    color: '#e74c3c'
  - entity: sensor.humidity
    name: Humidity
    color: '#3498db'
    y_axis: secondary
show:
  labels: true
  legend: true
  name: true
  state: true

查看

references/reference.md

获取完整配置选项，

examples/examples.md

获取更多配置示例。

CRITICAL: Valid Span Configuration

ApexCharts卡片（HACS）- 验证通过的配置

Always use one of these valid values for
span.end
:

yaml

span:
  end: minute   # Start of current minute
  end: hour     # Start of current hour (RECOMMENDED)
  end: day      # Start of current day
  end: week     # Start of current week
  end: month    # Start of current month
  end: year     # Start of current year
  end: isoWeek  # Start of ISO week (Monday)

Never use:

"now"

or other string values - these cause errors.

安装方法： HACS → 前端 → 搜索"apexcharts-card"

最佳适用场景： 高级可视化、出版级图表、复杂对比

Basic Time Series (VALIDATED)

重要提示：有效的Span配置

yaml

type: custom:apexcharts-card
header:
  show: true
  title: Temperature History
  show_states: true
graph_span: 24h
span:
  end: hour  # REQUIRED
yaxis:
  - min: 0
    max: 50
    decimals: 1
apex_config:
  chart:
    height: 200
  xaxis:
    type: datetime
    labels:
      datetimeFormatter:
        hour: "HH:mm"
  legend:
    show: true
series:
  - entity: sensor.temperature_living_room
    name: Living Room
    color: "#e74c3c"
    stroke_width: 2
  - entity: sensor.temperature_bedroom
    name: Bedroom
    color: "#3498db"
    stroke_width: 2

span.end
必须使用以下有效值之一：

yaml

span:
  end: minute   # 当前分钟开始
  end: hour     # 当前小时开始（推荐）
  end: day      # 当前天开始
  end: week     # 当前周开始
  end: month    # 当前月开始
  end: year     # 当前年开始
  end: isoWeek  # ISO周开始（周一）

禁止使用：

"now"

或其他字符串值 - 这些会导致错误。

Multi-Sensor with Dual Y-Axis (VALIDATED)

基础时间序列（验证通过）

yaml

type: custom:apexcharts-card
header:
  show: true
  title: Temperature & Humidity
  show_states: true
graph_span: 24h
span:
  end: hour
yaxis:
  - id: temp
    min: 0
    max: 50
    decimals: 1
  - id: humidity
    opposite: true
    min: 0
    max: 100
apex_config:
  chart:
    height: 250
  xaxis:
    type: datetime
    labels:
      datetimeFormatter:
        hour: "HH:mm"
series:
  - entity: sensor.temperature
    name: Temperature
    yaxis_id: temp
    color: '#e74c3c'
    stroke_width: 2
  - entity: sensor.humidity
    name: Humidity
    yaxis_id: humidity
    color: '#3498db'
    stroke_width: 2

yaml

type: custom:apexcharts-card
header:
  show: true
  title: Temperature History
  show_states: true
graph_span: 24h
span:
  end: hour  # 必填
yaxis:
  - min: 0
    max: 50
    decimals: 1
apex_config:
  chart:
    height: 200
  xaxis:
    type: datetime
    labels:
      datetimeFormatter:
        hour: "HH:mm"
  legend:
    show: true
series:
  - entity: sensor.temperature_living_room
    name: Living Room
    color: "#e74c3c"
    stroke_width: 2
  - entity: sensor.temperature_bedroom
    name: Bedroom
    color: "#3498db"
    stroke_width: 2

Supporting Files

多传感器双Y轴配置（验证通过）

examples/examples.md - Comprehensive real-world examples (climate dashboards, air quality, energy usage, multi-room comparisons, annotations, area charts)
references/reference.md - Technical depth (performance optimization, advanced ApexCharts configuration, troubleshooting, best practices, official documentation)

See

references/reference.md

for best practices, color schemes, troubleshooting, and performance optimization.

yaml

type: custom:apexcharts-card
header:
  show: true
  title: Temperature & Humidity
  show_states: true
graph_span: 24h
span:
  end: hour
yaxis:
  - id: temp
    min: 0
    max: 50
    decimals: 1
  - id: humidity
    opposite: true
    min: 0
    max: 100
apex_config:
  chart:
    height: 250
  xaxis:
    type: datetime
    labels:
      datetimeFormatter:
        hour: "HH:mm"
series:
  - entity: sensor.temperature
    name: Temperature
    yaxis_id: temp
    color: '#e74c3c'
    stroke_width: 2
  - entity: sensor.humidity
    name: Humidity
    yaxis_id: humidity
    color: '#3498db'
    stroke_width: 2

Notes

支持文件

History graphs automatically switch to long-term statistics for older data
ApexCharts
```
span.end
```
MUST use valid enum values (hour/day/week/month/year)
Mini-graph-card
```
points_per_hour
```
controls performance (lower = faster)
Statistics graphs are best for long-term trends (weeks/months)
Custom cards require HACS installation and HA restart

examples/examples.md - 全面的真实场景示例（气候控制面板、空气质量、能源使用、多房间对比、注释、面积图）
references/reference.md - 技术深度内容（性能优化、高级ApexCharts配置、故障排查、最佳实践、官方文档）

查看

references/reference.md

获取最佳实践、配色方案、故障排查和性能优化建议。

—

注意事项

—

History图表会自动为较旧数据切换到长期统计数据
ApexCharts的
```
span.end
```
必须使用有效的枚举值（hour/day/week/month/year）
Mini-graph-card的
```
points_per_hour
```
控制性能（值越小速度越快）
Statistics图表最适合长期趋势分析（周/月）
自定义卡片需要HACS安装并重启HA