ha-custom-cards

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Works with HACS installation (UI and API), Lovelace YAML dashboards, and custom card configurations.

支持HACS安装（UI和API方式）、Lovelace YAML仪表盘以及自定义卡片配置。

Home Assistant Custom Cards

Home Assistant自定义卡片

Configure HACS (Home Assistant Community Store) custom cards for enhanced dashboard visualizations.

配置HACS（Home Assistant社区商店）自定义卡片，增强仪表盘可视化效果。

Installed Cards

已支持的卡片

Card	Purpose	Repository ID
`mini-graph-card`	Compact sparkline graphs	151280062
`bubble-card`	Section separators with icons	680112919
`modern-circular-gauge`	Beautiful circular gauges	871730343
`lovelace-mushroom`	Modern entity cards	444350375
`apexcharts-card`	Advanced graphs with time axis	331701152

卡片名称	用途	仓库ID
`mini-graph-card`	紧凑的迷你折线图	151280062
`bubble-card`	带图标的区域分隔符	680112919
`modern-circular-gauge`	美观的圆形仪表盘	871730343
`lovelace-mushroom`	现代化实体卡片	444350375
`apexcharts-card`	带时间轴的高级图表	331701152

When to Use This Skill

适用场景

Use this skill when you need to:

Create circular gauge visualizations with color segments for temperature, humidity, or other metrics
Build advanced time-series graphs with ApexCharts for multi-sensor comparisons
Add section separators with icons using bubble-card for dashboard organization
Install HACS custom cards programmatically via WebSocket API
Troubleshoot ApexCharts span.end errors with validated configurations
Build modern Mushroom-style entity cards

Do NOT use when:

Native Home Assistant cards meet your needs (prefer built-in cards for simplicity)
You haven't verified entity IDs exist before using them in custom cards
Building dashboards without checking browser console for errors

当你需要以下操作时，可使用本技能：

为温度、湿度或其他指标创建带颜色分段的圆形仪表盘可视化
使用ApexCharts构建高级时间序列图表，用于多传感器对比
使用bubble-card添加带图标的区域分隔符，优化仪表盘布局
通过WebSocket API以编程方式安装HACS自定义卡片
使用经过验证的配置排查ApexCharts的span.end错误
构建现代化Mushroom风格的实体卡片

不适用场景：

Home Assistant原生卡片已满足需求（优先使用内置卡片以简化操作）
未验证实体ID是否存在就将其用于自定义卡片
未检查浏览器控制台错误就构建仪表盘

Quick Start

快速开始

All configurations in this skill are validated and tested. Critical errors (like ApexCharts

span.end

) are documented with solutions.

本技能中的所有配置均经过验证和测试。关键错误（如ApexCharts的

span.end

错误）已记录并提供解决方案。

Usage

使用步骤

Install via HACS: Use UI (HACS → Frontend → Search) or API (WebSocket
```
hacs/repository/download
```
)
Choose card type: Gauge (circular), graph (ApexCharts/mini-graph), separator (bubble-card), entity (mushroom)
Apply configuration: Copy validated YAML from examples below
Verify: Check browser console (F12) for errors, restart HA if card doesn't load
Customize: Adjust colors, min/max values, time spans based on sensor type

通过HACS安装：使用UI方式（HACS → 前端 → 搜索）或API方式（WebSocket的
```
hacs/repository/download
```
）
选择卡片类型：仪表盘（圆形）、图表（ApexCharts/mini-graph）、分隔符（bubble-card）、实体卡片（mushroom）
应用配置：复制下方示例中经过验证的YAML代码
验证配置：检查浏览器控制台（F12）是否有错误，若卡片未加载则重启Home Assistant
自定义调整：根据传感器类型调整颜色、最小值/最大值、时间范围

Modern Circular Gauge (VALIDATED)

现代化圆形仪表盘（已验证）

yaml

type: custom:modern-circular-gauge
entity: sensor.temperature
name: Temperature
min: 10
max: 40
needle: true
segments:
  - from: 10
    color: "#3498db"    # Cold - blue
  - from: 18
    color: "#2ecc71"    # Comfortable - green
  - from: 26
    color: "#f1c40f"    # Warm - yellow
  - from: 32
    color: "#e74c3c"    # Hot - red

yaml

type: custom:modern-circular-gauge
entity: sensor.temperature
name: Temperature
min: 10
max: 40
needle: true
segments:
  - from: 10
    color: "#3498db"    # 低温 - 蓝色
  - from: 18
    color: "#2ecc71"    # 舒适 - 绿色
  - from: 26
    color: "#f1c40f"    # 温暖 - 黄色
  - from: 32
    color: "#e74c3c"    # 高温 - 红色

ApexCharts with Time Axis (VALIDATED)

带时间轴的ApexCharts（已验证）

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: must be 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

重要提示：

span.end

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

yaml

type: custom:apexcharts-card
header:
  show: true
  title: 24小时历史数据
  show_states: true
graph_span: 24h
span:
  end: hour  # 必填：必须为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"}
```
→ ✅ 有效值

Bubble Card Separator

Bubble Card分隔符

yaml

type: custom:bubble-card
card_type: separator
name: Section Name
icon: mdi:thermometer

yaml

type: custom:bubble-card
card_type: separator
name: 区域名称
icon: mdi:thermometer

Mushroom Climate Card (VALIDATED)

Mushroom气候卡片（已验证）

yaml

type: custom:mushroom-climate-card
entity: climate.ac_unit
name: AC Name
hvac_modes:
  - "off"
  - cool
  - heat
  - auto
show_temperature_control: true
collapsible_controls: true

yaml

type: custom:mushroom-climate-card
entity: climate.ac_unit
name: 空调名称
hvac_modes:
  - "off"
  - cool
  - heat
  - auto
show_temperature_control: true
collapsible_controls: true

Common Patterns

常见布局模式

Grid Layout with Gauges

仪表盘网格布局

yaml

type: grid
columns: 3
square: false
cards:
  - type: custom:modern-circular-gauge
    entity: sensor.officeht_temperature
    name: Temperature
    min: 10
    max: 40
    needle: true
    segments:
      - from: 10
        color: "#3498db"
      - from: 18
        color: "#2ecc71"
      - from: 26
        color: "#f1c40f"
      - from: 32
        color: "#e74c3c"
  - type: custom:modern-circular-gauge
    entity: sensor.officeht_humidity
    name: Humidity
    min: 0
    max: 100
    needle: true
    segments:
      - from: 0
        color: "#e74c3c"
      - from: 30
        color: "#f1c40f"
      - from: 40
        color: "#2ecc71"
      - from: 60
        color: "#f1c40f"
      - from: 70
        color: "#e74c3c"

See

examples/examples.md

for complete environmental dashboard section with separators and graphs.

yaml

type: grid
columns: 3
square: false
cards:
  - type: custom:modern-circular-gauge
    entity: sensor.officeht_temperature
    name: Temperature
    min: 10
    max: 40
    needle: true
    segments:
      - from: 10
        color: "#3498db"
      - from: 18
        color: "#2ecc71"
      - from: 26
        color: "#f1c40f"
      - from: 32
        color: "#e74c3c"
  - type: custom:modern-circular-gauge
    entity: sensor.officeht_humidity
    name: Humidity
    min: 0
    max: 100
    needle: true
    segments:
      - from: 0
        color: "#e74c3c"
      - from: 30
        color: "#f1c40f"
      - from: 40
        color: "#2ecc71"
      - from: 60
        color: "#f1c40f"
      - from: 70
        color: "#e74c3c"

查看

examples/examples.md

获取包含分隔符和图表的完整环境仪表盘区域示例。

ApexCharts Advanced Features

ApexCharts高级功能

Valid Span Configuration (VALIDATED)

有效的Span配置（已验证）

CRITICAL: Always use one of these valid values for

span.end

yaml

span:
  end: minute   # Start of current minute
  end: hour     # Start of current hour
  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.

重要提示：

span.end

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

yaml

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

禁止使用：

"now"

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

Dual Y-Axis

双Y轴

yaml

type: custom:apexcharts-card
header:
  show: true
  title: Temperature & Humidity
graph_span: 24h
span:
  end: hour
yaxis:
  - id: temp
    min: 0
    max: 50
    decimals: 1
  - id: humidity
    opposite: true
    min: 0
    max: 100
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: 温度与湿度
graph_span: 24h
span:
  end: hour
yaxis:
  - id: temp
    min: 0
    max: 50
    decimals: 1
  - id: humidity
    opposite: true
    min: 0
    max: 100
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

Annotations (Sunrise/Sunset)

标注（日出/日落）

WARNING: JavaScript template annotations may cause errors. Use with caution.

yaml

apex_config:
  annotations:
    xaxis:
      - x: "${ new Date(states['sun.sun'].attributes.next_rising).getTime() }"
        borderColor: "#FFA500"
        label:
          text: Sunrise
          style:
            background: "#FFA500"

Note: If annotations cause configuration errors, remove them or use static timestamps instead.

See

references/reference.md

for complete ApexCharts advanced features and time formatting options.

注意：JavaScript模板标注可能会导致错误，请谨慎使用。

yaml

apex_config:
  annotations:
    xaxis:
      - x: "${ new Date(states['sun.sun'].attributes.next_rising).getTime() }"
        borderColor: "#FFA500"
        label:
          text: 日出
          style:
            background: "#FFA500"

说明：如果标注导致配置错误，请移除标注或使用静态时间戳替代。

查看

references/reference.md

获取完整的ApexCharts高级功能和时间格式化选项。

Supporting Files

支持文件

examples/examples.md - Comprehensive examples (environmental dashboard section, grid layouts, mushroom cards, ApexCharts patterns)
references/reference.md - Color schemes, HACS installation (UI and API), troubleshooting, best practices, official documentation

examples/examples.md - 综合示例（环境仪表盘区域、网格布局、Mushroom卡片、ApexCharts模式）
references/reference.md - 配色方案、HACS安装（UI和API方式）、故障排查、最佳实践、官方文档

HACS Installation

HACS安装方式

Via UI

UI方式

Open HACS → Frontend
Search for card name
Click Download
Restart Home Assistant

打开HACS → 前端
搜索卡片名称
点击下载
重启Home Assistant

Via API (Programmatic)

API方式（编程式）

python

import json
import websocket

ws_url = "ws://192.168.68.123:8123/api/websocket"
ws = websocket.create_connection(ws_url)

python

import json
import websocket

ws_url = "ws://192.168.68.123:8123/api/websocket"
ws = websocket.create_connection(ws_url)

Auth

认证

ws.recv() ws.send(json.dumps({ "type": "auth", "access_token": os.environ["HA_LONG_LIVED_TOKEN"] })) ws.recv()

Install card by repository ID

通过仓库ID安装卡片

ws.send(json.dumps({ "id": 1, "type": "hacs/repository/download", "repository": 151280062, # mini-graph-card })) response = json.loads(ws.recv()) ws.close()

undefined

ws.send(json.dumps({ "id": 1, "type": "hacs/repository/download", "repository": 151280062, # mini-graph-card })) response = json.loads(ws.recv()) ws.close()

undefined

Common Error Patterns

常见错误排查

1. ApexCharts span error

1. ApexCharts span错误

Check

span.end

uses valid value (hour/day/week/month/year)

yaml

undefined

检查

span.end

是否使用有效值（hour/day/week/month/year）

yaml

undefined

WRONG

错误示例

span: end: now # ❌

CORRECT

正确示例

span: end: hour # ✅

undefined

span: end: hour # ✅

undefined

2. Entity not found

2. 实体未找到

Verify entity exists in Developer Tools → States

在开发者工具 → 状态页面验证实体是否存在

3. Card not loading

3. 卡片未加载

Check HACS installation and browser console (F12)

检查HACS安装情况和浏览器控制台（F12）

4. JavaScript template error

4. JavaScript模板错误

Remove or simplify template annotations

See

references/reference.md

for complete troubleshooting guide.

移除或简化模板标注

查看

references/reference.md

获取完整的故障排查指南。

Best Practices

最佳实践

Use meaningful colors: Red for warnings/hot, blue for cold/water, green for normal
Test incrementally: Add cards one at a time and validate
Check browser console: View errors in browser console (F12)
Validate entities: Ensure entity IDs exist before using in cards
Restart HA after HACS install: Custom cards require restart to activate

使用有意义的颜色：红色表示警告/高温，蓝色表示低温/水，绿色表示正常
增量测试：逐个添加卡片并验证配置
检查浏览器控制台：通过浏览器控制台（F12）查看错误
验证实体：在使用实体ID前确保其存在
安装HACS卡片后重启HA：自定义卡片需要重启才能激活

Notes

注意事项

ApexCharts
```
span.end
```
MUST use valid enum values (minute/hour/day/week/month/year/isoWeek)
All HACS cards require Home Assistant restart after installation
Repository IDs: mini-graph-card (151280062), apexcharts-card (331701152), bubble-card (680112919)
JavaScript template annotations may cause errors - test before deploying
Use Developer Tools → States to verify entity IDs exist

ApexCharts的
```
span.end
```
必须使用有效的枚举值（minute/hour/day/week/month/year/isoWeek）
所有HACS卡片在安装后都需要重启Home Assistant
仓库ID：mini-graph-card（151280062）、apexcharts-card（331701152）、bubble-card（680112919）
JavaScript模板标注可能会导致错误 - 部署前请测试
使用开发者工具 → 状态页面验证实体ID是否存在