【Bubble Card 實作】做出一頁「橫向導覽 + 手機 App 式彈窗」的控制面板

charles · 發表於 2026-9-21 13:00:10

這篇的內容（15 段）

做完這篇你會有什麼
⚠ 先講一件會讓你白忙的事
第一步：裝 HACS
情況 B：Docker Container
情況 C：Core / venv
三種情況共通的收尾
第二步：下載 Bubble Card
第四步：button 卡片的四種型態
4-2 switch：純開關
7-1 建立彈窗
7-2 叫出彈窗
7-3 用自動化或感測器觸發彈窗
第十一步：模組商店
除錯對照表
要不要用它，一個務實的建議

這篇從「HACS 都還沒裝」開始，做到一整頁可以直接用的控制面板：上面一排可左右捲的房間按鈕，點下去從底部滑出一個彈窗，裡面是那個房間的完整控制。

Bubble Card 自己帶樣式系統，不需要 card-mod。

每一步都有「你會看到什麼」。做完第三步能自己確認第三步成功了，才走第四步。

做完這篇你會有什麼

五種子卡片各一份完整設定：button、separator、pop-up、horizontal-buttons-stack、sub-buttons
一頁組好的成品，整段貼進原始設定編輯器、改實體 ID 就能用
知道怎麼不靠 card-mod 改它的外觀

⚠ 先講一件會讓你白忙的事

網路上大量的 Bubble Card 彈窗範例，是先放一張 `vertical-stack`，把 pop-up 卡片當成裡面第一張。那是 3.x 之前的舊結構。

現在的 pop-up 卡片自己就有 `cards:` 可以放內容，照舊寫法做會得到一個結構怪異、之後很難維護的東西。這篇用的是目前的寫法。

---

第一步：裝 HACS

Bubble Card 不是內建的，要透過 HACS 下載。先在 HA 網址列打 /config/info 看你是哪一種安裝方式，然後對號入座。

情況 A：Home Assistant OS 或 Supervised（大多數人）

官方現在建議用附加元件裝，不用 SSH、不用打指令：

「設定 → 附加元件 → 右下角附加元件商店」
右上角三個點 → 存放庫
貼上 https://github.com/hacs/addons → 新增 → 關閉
回商店往下捲，找到 Get HACS → 安裝 → 啟動
切到它的日誌分頁

你會看到什麼：日誌印出檔案已放好，並要你重啟 HA。照做（設定 → 系統 → 右上角重新啟動）。

情況 B：Docker Container

docker exec -it homeassistant bash
wget -O - https://get.hacs.xyz | bash -
exit
docker restart homeassistant

複製代碼

（容器名字用 `docker ps` 查，不一定叫 `homeassistant`。）

情況 C：Core / venv

切到跑 HA 的使用者，在設定目錄底下跑 `wget -O - https://get.hacs.xyz | bash -`，然後重啟。

三種情況共通的收尾

重啟完按 Ctrl+Shift+R 硬重新整理
「設定 → 裝置與服務 → 新增整合」→ 搜尋 HACS
三個確認方塊全部勾起來 → 送出
畫面給你一串代碼跟 github.com/login/device 的連結，開連結貼代碼按授權

你會看到什麼：左側選單多出一個 HACS 項目。

搜尋不到 HACS 這個整合 → 檔案沒進 `custom_components/hacs/`，或你沒重啟。重啟那步不能省。

授權一直失敗 → 查兩件事：主機有沒有對外網路、主機的系統時間準不準。時間差太多會讓 GitHub 的授權握手失敗，而錯誤訊息完全看不出是時間問題。

---

第二步：下載 Bubble Card

左側選單點 HACS
搜尋 Bubble Card
點結果（作者 Clooos）→ 右下角下載 → 確認
下載完會提示重新整理瀏覽器，按 Ctrl+Shift+R

確認資源有登記進去：「設定 → 儀表板 → 右上三個點 → 資源」，清單裡應該有一行 `/hacsfiles/Bubble-Card/bubble-card.js`，類型是 JavaScript 模組。

看不到「資源」這個選單項 → 你的帳號沒開進階模式：點左下角你的名字 → 往下捲 → 打開 進階模式。

---

第三步：確認它真的載入了（不要跳過）

自訂卡片沒載入時的症狀很明確，先學會辨認：

打開儀表板 → 右上角鉛筆 → + 新增卡片 → 最底下選 手動 Manual
文字框清空，貼進去：

type: custom:bubble-card
card_type: button
entity: light.living_room
name: 測試
icon: mdi:sofa

複製代碼

你會看到什麼：右邊預覽出現一張圓角長條形的卡片，左邊一個圓形圖示底座、右邊寫著「測試」，整體比 HA 原生卡片扁一點、圓一點。

以下還有約 81% 的內容
登入後即可閱讀完整教學

登入繼續閱讀使用 Google 登入

		自動登入	找回密碼
密碼			立即註冊

【Bubble Card 實作】做出一頁「橫向導覽 + 手機 App 式彈窗」的控制面板

延伸閱讀

瀏覽過的版塊