ha-dashboard

Home Assistant 仪表板技能

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

开始之前

此技能可避免 5 个常见错误，并节省约 40% 的令牌用量。

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

此技能可避免的已知问题

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

快速开始

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

# configuration.yaml
lovelace:
  mode: yaml

原因： YAML 模式可让你完全控制仪表板配置，并启用版本控制。

第 2 步：创建基本仪表板结构

# ui-lovelace.yaml or dashboards.yaml
title: My Home
views:
  - title: Home
    path: home
    cards:
      - type: markdown
        content: Welcome to your dashboard!

原因： 这个最简结构可在增加复杂内容之前验证 YAML 配置。

第 3 步：向视图添加卡片

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

原因： 卡片是构建仪表板的基础——先从简单卡片开始，再添加复杂卡片。

关键规则

务必做到

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

切勿

• 使用制表符缩进
• 硬编码可能会变更的实体名称
• 创建包含 20 张以上卡片的视图（拆分为多个视图）
• 忘记在天气预报卡片中设置 forecast_type（自 2023 年起为必需项）
• 未了解模式的情况下混用由 UI 管理和由 YAML 管理的仪表板

常见错误

错误：

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

正确：

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

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

预防已知问题

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

配置参考

仪表板配置（configuration.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，通过 UI 编辑使用 storage
• resources：加载自定义卡片/CSS（仅限 YAML 模式）
• dashboards：定义其他仪表板

视图配置

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

常见模式

水平按钮堆栈

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

条件式卡片显示

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

随附资源

参考资料

位于 references/：

• card-reference.md - 所有内置卡片类型及 YAML 示例
• view-types.md - 视图布局比较和选择指南
• theme-variables.md - 用于主题设置的 CSS 变量
• common-patterns.md - 条件可见性、堆栈和实体行

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

资源文件

位于 assets/：

• dashboard-template.yaml - 仪表板配置起始模板
• card-snippets.yaml - 可复制粘贴的卡片示例

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

Context7 文档

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

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

官方文档

• 仪表盘概览
• 卡片类型
• 视图
• 主题
• 自定义卡片（开发者）

故障排除

仪表盘显示空白

症状： 仪表盘加载后不显示任何内容或出现错误。

解决方法：

# Check Home Assistant logs
ha core logs | grep -i lovelace

# Validate YAML online or locally
python -c "import yaml; yaml.safe_load(open('ui-lovelace.yaml'))"

自定义卡片未加载

症状： 出现“Custom element doesn't exist”错误。

解决方法：

# 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

设置检查清单

使用此技能前，请确认：

• Home Assistant 正在运行（2023.1+）
• 你可以访问配置文件（File Editor 或 VS Code 插件）
• 你知道实体 ID（查看 Developer Tools > States）
• 你已决定使用 YAML 还是 UI 模式管理仪表盘