Home Assistant 中文文档 下载 App

HACS 社区自定义卡片安装指南

HACS 是什么

HACS（Home Assistant Community Store（简称 HACS）是 Home Assistant 生态里最关键的社区工具——它是一个应用商店，可以让你一键安装数千社区开发者贡献的自定义卡片、集成、主题和 Python 脚本，而不需要手动去 GitHub 上到处找文件、复制到配置目录、刷新前端缓存。

安装 HACS

Home Assistant OS 用户（推荐方式）：

  1. Settings → Apps → 搜索 Home Assistant Community Store
  2. 如果搜不到，先添加仓库：Apps → 右上角三点 → Add repository → 类型选 URL → 填 https://github.com/hacs/addons → 类别选 App
  3. 安装 HACS，启动一次（不需要设"开机自启"）
  4. 打开 HACS 应用，按提示完成首次配置（需要 GitHub Token）

Container / Core 用户（需要手动安装）：

参考 HACS 官方文档的 Container 安装路径。

用 HACS 安装自定义卡片

  1. 侧边栏点击 HACS
  2. 顶部切换到 Frontend 标签（卡片都在这里）
  3. 点击右下角 Explore & download
  4. 浏览或搜索你想要的卡片，点进去看说明和示例
  5. 点 Download → 等待下载完成
  6. HACS 会提示你刷新前端（F5）——刷新后新卡片就可以在 Lovelace 编辑器里选到了

必装的自定义卡片（精选）

界面增强类

卡片用途
button-card极度灵活的自定义按钮，可以用模板控制颜色/图标/点击行为
card-mod给任意卡片注入自定义 CSS（改颜色、圆角、阴影…）
mini-graph-card极简折线图，比内置的 History Graph 好看得多
bar-card横向/纵向条形图，适合显示百分比/进度
mushroom-cards一套设计语言统一的完整卡片集（按钮、灯、空调…）

设备专用类

卡片用途
Xiaomi Miot Spec Card小米设备专用卡片（灯/空调/净化器/电饭煲…）
vacuum-card扫地机器人控制卡片（拖地/回充/地图…）
alarmo-card报警控制面板
clock-weather-card时钟 + 天气组合，极简风格

功能类

卡片用途
auto-entities根据条件自动生成 entities 列表（如"显示所有状态为 on 的灯"）
layout-card更灵活的网格/瀑布流布局，比内置 Grid 强大
browser-mod浏览器级别的增强（弹出通知、语音朗读、全屏视频…）
swipe-card可以左右滑动切换的卡片容器

自定义卡片的 YAML 写法

HACS 安装的自定义卡片在 YAML 里用 type: custom:卡片名 的格式：

type: custom:button-card
name: 客厅灯
entity: light.living_room
tap_action:
  action: toggle
icon: mdi:lightbulb
state:
  - operator: "=="
    value: "on"
    style:
      color: green
  - operator: "default"
    style:
      color: gray

常见问题

HACS 卡片装好但 Lovelace 编辑器里找不到

刷新前端（F5）。如果还不行，Settings → System → Restart → Restart Home Assistant。

HACS 无法访问 GitHub

Home Assistant 需要能访问 github.com。如果网络环境受限，可以考虑给 Home Assistant 配置 HTTP 代理，或者手动从 GitHub 下载 .js 文件放到 config/www/community/卡片名/ 目录。

自定义卡片升级

HACS 会在有新版本时在侧边栏图标上显示小红点。进 HACS → Updates → 点 Update 即可。

写在前面的警告

社区自定义卡片虽然强大，但质量参差不齐。以下是使用建议：