ha-dashboard

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Home Assistant Dashboard Skill

Configure Lovelace dashboards, cards, views, and themes for Home Assistant.

配置Home Assistant的Lovelace仪表盘、卡片、视图和主题。

Before You Start

开始之前

This skill prevents 5 common errors and saves ~40% tokens.

Metric	Without Skill	With Skill
Setup Time	30+ min	10 min
Common Errors	5	0
Token Usage	~8000	~4800

该技能可避免5种常见错误并节省约40%的令牌消耗。

指标	未使用技能	使用技能
设置时间	30+ 分钟	10 分钟
常见错误	5	0
令牌使用	~8000	~4800

Known Issues This Skill Prevents

该技能可避免的已知问题

YAML indentation errors (must use 2 spaces, never tabs)
Invalid entity ID format (must be
```
domain.entity_name
```
)
Missing required card properties (e.g.,
```
entity
```
for button cards)
Incorrect view type configuration
Theme variables with wrong syntax

YAML缩进错误（必须使用2个空格，绝对不能用制表符）
无效实体ID格式（必须为
```
domain.entity_name
```
）
缺少卡片必填属性（例如按钮卡片的
```
entity
```
）
视图类型配置错误
主题变量语法错误

Quick Start

快速开始

Step 1: Enable YAML Mode (Optional)

步骤1：启用YAML模式（可选）

yaml

undefined

yaml

undefined

configuration.yaml

lovelace: mode: yaml


**Why this matters:** YAML mode gives full control over dashboard configuration and enables version control.

lovelace: mode: yaml


**为什么这很重要：** YAML模式让你完全掌控仪表盘配置并支持版本控制。

Step 2: Create Basic Dashboard Structure

步骤2：创建基础仪表盘结构

yaml

undefined

yaml

undefined

ui-lovelace.yaml or dashboards.yaml

title: My Home views:

title: Home path: home cards:
- type: markdown content: Welcome to your dashboard!


**Why this matters:** This minimal structure validates your YAML setup before adding complexity.

title: My Home views:

title: Home path: home cards:
- type: markdown content: "Welcome to your dashboard!"


**为什么这很重要：** 这个极简结构可在添加复杂配置前验证你的YAML设置是否正确。

Step 3: Add Cards to Views

步骤3：为视图添加卡片

yaml

views:
  - title: Living Room
    path: living-room
    cards:
      - type: entities
        title: Lights
        entities:
          - light.living_room
          - light.kitchen
      - type: weather-forecast
        entity: weather.home
        forecast_type: daily

Why this matters: Cards are the building blocks of dashboards - start with simple cards before complex ones.

yaml

views:
  - title: Living Room
    path: living-room
    cards:
      - type: entities
        title: Lights
        entities:
          - light.living_room
          - light.kitchen
      - type: weather-forecast
        entity: weather.home
        forecast_type: daily

为什么这很重要： 卡片是仪表盘的构建模块——先从简单卡片入手，再尝试复杂卡片。

Critical Rules

关键规则

Always Do

必须遵守

Use 2-space indentation consistently
Use entity ID format:
```
domain.entity_name
```
(e.g.,
```
light.living_room
```
)
Validate YAML before reloading (use an online YAML validator)
Define
```
tap_action
```
for interactive cards
Test on mobile devices

始终统一使用2个空格缩进
使用
```
domain.entity_name
```
格式的实体ID（例如
```
light.living_room
```
）
重新加载前验证YAML（使用在线YAML验证工具）
为交互式卡片定义
```
tap_action
```
在移动设备上测试

Never Do

绝对禁止

Use tabs for indentation
Hardcode entity names that might change
Create views with 20+ cards (split into multiple views)
Forget
```
forecast_type
```
on weather-forecast cards (required since 2023)
Mix UI-managed and YAML-managed dashboards without understanding the mode

使用制表符进行缩进
硬编码可能会变更的实体名称
创建包含20张以上卡片的视图（拆分为多个视图）
天气预报卡片遗漏
```
forecast_type
```
（2023年起为必填项）
在未理解模式的情况下混用UI管理和YAML管理的仪表盘

Common Mistakes

常见错误示例

Wrong:

yaml

type: button
entity:light.living_room
  tap_action:
    action: toggle

Correct:

yaml

type: button
entity: light.living_room
tap_action:
  action: toggle

Why: Missing space after colon and incorrect indentation are the most common YAML errors.

错误写法：

yaml

type: button
entity:light.living_room
  tap_action:
    action: toggle

正确写法：

yaml

type: button
entity: light.living_room
tap_action:
  action: toggle

原因： 冒号后缺少空格和缩进错误是最常见的YAML错误。

Known Issues Prevention

已知问题解决方案

Issue	Root Cause	Solution
"Unknown card type"	Missing custom card resource	Add to `lovelace.resources`
Cards not updating	Browser cache	Hard refresh (Ctrl+Shift+R)
Theme not applying	Wrong variable name	Check theme variable spelling
Blank dashboard	YAML syntax error	Validate YAML, check logs
Entity unavailable	Wrong entity ID	Check entity in Developer Tools > States

问题	根本原因	解决方案
"Unknown card type"（未知卡片类型）	缺少自定义卡片资源	添加至 `lovelace.resources`
卡片不更新	浏览器缓存	强制刷新（Ctrl+Shift+R）
主题不生效	变量名称错误	检查主题变量拼写
仪表盘空白	YAML语法错误	验证YAML，查看日志
实体不可用	实体ID错误	在开发者工具 > 状态中检查实体

Configuration Reference

配置参考

Dashboard Configuration (configuration.yaml)

仪表盘配置（configuration.yaml）

yaml

lovelace:
  mode: yaml                    # or 'storage' for UI mode
  resources:
    - url: /local/card.js       # Custom card resources
      type: module
  dashboards:
    lovelace-custom:
      mode: yaml
      title: Custom
      icon: mdi:view-dashboard
      show_in_sidebar: true
      filename: custom-dashboard.yaml

Key settings:

```
mode
```
:
```
yaml
```
for manual control,
```
storage
```
for UI editing
```
resources
```
: Load custom cards/CSS (only in YAML mode)
```
dashboards
```
: Define additional dashboards

yaml

lovelace:
  mode: yaml                    # or 'storage' for UI mode
  resources:
    - url: /local/card.js       # Custom card resources
      type: module
  dashboards:
    lovelace-custom:
      mode: yaml
      title: Custom
      icon: mdi:view-dashboard
      show_in_sidebar: true
      filename: custom-dashboard.yaml

关键设置：

```
mode
```
：
```
yaml
```
表示手动控制，
```
storage
```
表示UI编辑模式
```
resources
```
：加载自定义卡片/CSS（仅YAML模式支持）
```
dashboards
```
：定义额外的仪表盘

View Configuration

视图配置

yaml

views:
  - title: View Name           # Tab title
    path: view-path            # URL path (/lovelace/view-path)
    icon: mdi:home             # Tab icon (optional)
    type: masonry              # masonry, panel, sections, sidebar
    theme: dark-mode           # Apply specific theme
    subview: false             # Hide from navigation
    cards: []                  # Card list

yaml

views:
  - title: View Name           # Tab title
    path: view-path            # URL path (/lovelace/view-path)
    icon: mdi:home             # Tab icon (optional)
    type: masonry              # masonry, panel, sections, sidebar
    theme: dark-mode           # Apply specific theme
    subview: false             # Hide from navigation
    cards: []                  # Card list

Common Patterns

常见模式

Horizontal Stack of Buttons

按钮水平堆叠

yaml

type: horizontal-stack
cards:
  - type: button
    entity: light.living_room
    name: Living
    tap_action:
      action: toggle
  - type: button
    entity: light.bedroom
    name: Bedroom
    tap_action:
      action: toggle

yaml

type: horizontal-stack
cards:
  - type: button
    entity: light.living_room
    name: Living
    tap_action:
      action: toggle
  - type: button
    entity: light.bedroom
    name: Bedroom
    tap_action:
      action: toggle

Conditional Card Display

条件卡片显示

yaml

type: conditional
conditions:
  - condition: state
    entity: binary_sensor.home_occupied
    state: "on"
card:
  type: entities
  title: Home Controls
  entities:
    - light.living_room
    - climate.thermostat

yaml

type: conditional
conditions:
  - condition: state
    entity: binary_sensor.home_occupied
    state: "on"
card:
  type: entities
  title: "Home Controls"
  entities:
    - light.living_room
    - climate.thermostat

Bundled Resources

配套资源

References

参考文档

Located in

references/

```
card-reference.md
```
- All built-in card types with YAML examples
```
view-types.md
```
- View layout comparison and selection guide
```
theme-variables.md
```
- CSS variables for theming
```
common-patterns.md
```
- Conditional visibility, stacks, entity rows

Note: For deep dives on specific topics, see the reference files above.

位于

references/

目录下：

```
card-reference.md
```
- 所有内置卡片类型及YAML示例
```
view-types.md
```
- 视图布局对比与选择指南
```
theme-variables.md
```
- 主题定制用CSS变量
```
common-patterns.md
```
- 条件可见性、堆叠布局、实体行配置

注意： 如需深入了解特定主题，请查看上述参考文件。

Assets

资源模板

Located in

assets/

```
dashboard-template.yaml
```
- Starter dashboard configuration
```
card-snippets.yaml
```
- Copy-paste card examples

Copy these templates as starting points for your implementation.

位于

assets/

目录下：

```
dashboard-template.yaml
```
- 仪表盘启动配置模板
```
card-snippets.yaml
```
- 可直接复制使用的卡片示例

可复制这些模板作为你的实现起点。

Context7 Documentation

Context7 文档

For current documentation, use these Context7 library IDs:

Library ID	Purpose
`/home-assistant/home-assistant.io`	User docs - dashboards, cards, views, themes
`/home-assistant/developers.home-assistant`	Developer docs - custom card development
`/hacs/documentation`	HACS frontend cards

如需最新文档，请使用以下Context7库ID：

库ID	用途
`/home-assistant/home-assistant.io`	用户文档 - 仪表盘、卡片、视图、主题
`/home-assistant/developers.home-assistant`	开发者文档 - 自定义卡片开发
`/hacs/documentation`	HACS前端卡片

Official Documentation

官方文档

Troubleshooting

故障排除

Dashboard Shows Blank

仪表盘显示空白

Symptoms: Dashboard loads but shows nothing or error.

Solution:

bash

undefined

症状： 仪表盘加载后显示空白或错误。

解决方案：

bash

undefined

Check Home Assistant logs

查看Home Assistant日志

ha core logs | grep -i lovelace

Validate YAML online or locally

在线或本地验证YAML

python -c "import yaml; yaml.safe_load(open('ui-lovelace.yaml'))"

undefined

python -c "import yaml; yaml.safe_load(open('ui-lovelace.yaml'))"

undefined

Custom Card Not Loading

自定义卡片无法加载

Symptoms: "Custom element doesn't exist" error.

Solution:

yaml

undefined

症状： 出现"Custom element doesn't exist"（自定义元素不存在）错误。

解决方案：

yaml

undefined

Ensure resource is loaded

确保已加载资源

lovelace: resources: - url: /local/my-card.js type: module # or 'js' for non-module

Check file exists at /config/www/my-card.js

检查文件是否存在于/config/www/my-card.js路径下

undefined

undefined

Setup Checklist

设置检查清单

Before using this skill, verify:

Home Assistant is running (2023.1+)
You have access to configuration files (File Editor or VS Code add-on)
You know your entity IDs (check Developer Tools > States)
You've decided on YAML vs UI mode for dashboard management

使用该技能前，请确认：

Home Assistant已运行（版本2023.1+）
你有权访问配置文件（通过文件编辑器或VS Code插件）
你知晓自己的实体ID（在开发者工具 > 状态中查看）
已确定仪表盘管理使用YAML模式还是UI模式