安裝 ha-floorplan，把你的 SVG 接上 HA（第一個會動的實體）

charles

上一篇畫好 SVG 了，這篇把它接上 HA。

目標：做完這篇，點一下 SVG 上的客廳，燈會開關。



第一步：用 HACS 安裝

• 打開 HACS
  
• 右上角三個點 → 自訂儲存庫（Custom repositories）
  
• 網址填 experiencelovelace/ha-floorplan
  
• 類別選 Dashboard（或 Lovelace，看你的 HACS 版本）
  
• 加入之後，在 HACS 裡搜尋 floorplan → 下載
  
• 重新整理瀏覽器（Ctrl+F5）
  

有些版本的 HACS 已經收錄了，可以先直接搜尋看看，有的話就不用加自訂儲存庫。

第二步：建立一個 CSS 檔案

這一步不能省 —— ha-floorplan 一定要有一個樣式表。

建立 /config/www/floorplan/home.css：

1. /* 燈關著的房間 */
2. .light-off {
3.   fill: #F4F6FA;
4.   transition: fill 0.8s ease-in-out;
5.   cursor: pointer;
6. }
8. /* 燈開著的房間 */
9. .light-on {
10.   fill: #FFD54F;
11.   transition: fill 0.8s ease-in-out;
12.   cursor: pointer;
13. }

複製代碼

就這樣，兩個 class。

第三步：加入卡片

在儀表板加一張手動卡片（Manual card），貼上：

1. type: custom:floorplan-card
2. full_height: true
3. config:
4.   image: /local/floorplan/home.svg
5.   stylesheet: /local/floorplan/home.css
6.   log_level: info
7.   console_log_level: info
9.   defaults:
10.     hover_action: hover-info
11.     tap_action: more-info
13.   rules:
14.     - name: 燈光
15.       entities:
16.         - light.living_room
17.         - light.kitchen
18.         - light.bedroom
19.       tap_action: toggle
20.       state_action:
21.         action: call-service
22.         service: floorplan.class_set
23.         service_data: '${entity.state === "on" ? "light-on" : "light-off"}'

複製代碼

儲存。

如果一切順利：你的 SVG 出現了，而且點客廳會開關燈、房間會變黃色。



這段設定在講什麼

image —— 你的 SVG 檔案。

stylesheet —— 剛剛建的 CSS。

log_level: info —— 這個非常重要。

開了之後，ha-floorplan 會在卡片底下顯示一個記錄面板，
告訴你哪些 SVG 元素找不到、哪個 id 拼錯了。

第一次設定一定要開，正常運作之後再改成 warning。

rules —— 規則清單，這是核心。

每一條規則說的是：

• entities —— 哪些實體
  
• tap_action —— 點下去做什麼
  
• state_action —— 狀態改變時做什麼
  

怎麼對應到 SVG 元素

預設是「實體 ID = SVG 元素的 id」。

所以你上一篇把客廳的方形 id 設成 light.living_room，
規則裡寫 light.living_room，它就自動找到了。

想要一個實體對應多個元素（例如房間 + 圖示 + 文字），
用 elements 明確指定：

1.     - entity: light.living_room
2.       elements:
3.         - light.living_room
4.         - icon.living_room
5.         - label.living_room
6.       tap_action: toggle

複製代碼

四個核心的動作服務



ha-floorplan 提供幾個專用的服務，這是它的精華：

floorplan.class_set —— 換 CSS class（最常用）

1.       state_action:
2.         action: call-service
3.         service: floorplan.class_set
4.         service_data: '${entity.state === "on" ? "light-on" : "light-off"}'

複製代碼

狀態改變時，把元素的 class 換掉，剩下的交給 CSS。

這是最乾淨的做法 —— 邏輯在 YAML、外觀在 CSS。

floorplan.style_set —— 直接改行內樣式

1.       state_action:
2.         action: call-service
3.         service: floorplan.style_set
4.         service_data: >
5.           ${'fill: rgb(' + Math.round(entity.attributes.brightness || 0) + ', 200, 80)'}

複製代碼

適合需要「連續變化」的效果（下一篇會講）。

floorplan.text_set —— 換文字內容

1.     - entity: sensor.living_room_temperature
2.       state_action:
3.         action: call-service
4.         service: floorplan.text_set
5.         service_data: '${entity.state + "°"}'

複製代碼

讓 SVG 裡的文字元素顯示實體的值。

floorplan.image_set —— 換圖片

用在「不同狀態顯示不同圖示」的場合。

那個 ${...} 是什麼

那是 JavaScript 運算式。

1. ${entity.state === "on" ? "light-on" : "light-off"}

複製代碼

翻成白話：如果實體的狀態是 on，就回傳 "light-on"，否則回傳 "light-off"。

你可以用到的變數：

• entity —— 那個實體的完整物件
  
• entity.state —— 狀態字串
  
• entity.attributes.xxx —— 屬性
  
• entities —— 所有實體（可以參照別的實體）
  
• hass —— HA 的完整物件（進階用）
  

不會 JavaScript 也沒關係，
九成的情況你只需要上面那個三元運算式，複製改一下就好。

一個注意：ha-floorplan 是社群專案，
語法在版本之間有調整過（舊版用 return ...、新版用 ${...}）。

看你裝到的版本的官方文件為準 ——
如果照這篇寫沒反應，先去文件確認語法。



第一次通常會遇到的四個狀況

狀況一：什麼都沒顯示（空白卡片）

• SVG 路徑錯了 → 在瀏覽器直接打開 /local/floorplan/home.svg 測試
  
• 或者 HACS 裝完沒清快取 → Ctrl+F5
  
• 或者卡片型別打錯 → 要是 custom:floorplan-card
  

狀況二：SVG 顯示了，但點了沒反應

九成是 id 對不上。

• 開 log_level: info，看記錄面板說什麼
  
• 通常會看到「找不到元素 light.living_room」
  
• 回 Inkscape 檢查 id 有沒有打錯（大小寫有差）
  

狀況三：點得到但房間不變色

• CSS 檔案路徑錯了
  
• 或者 class 名稱在 CSS 和 YAML 裡對不上
  
• 或者 CSS 裡的 fill 被 SVG 元素本身的 style="fill:#xxx" 蓋過去了
  

第三個很常見。Inkscape 會把顏色寫成元素的行內樣式，
行內樣式的優先權比外部 CSS 高。

解法：在 CSS 加 !important：

1. .light-on {
2.   fill: #FFD54F !important;
3. }

複製代碼

或者更乾淨的做法：在 Inkscape 的 XML 編輯器裡
把那個元素的 style 屬性刪掉，讓 CSS 全權負責。

狀況四：圖片破掉

如果你的 SVG 裡有連結的 PNG：

• 回 Inkscape 用「擴充功能 → 圖片 → 嵌入圖片」轉成嵌入
  
• 或者在設定裡加路徑前綴（看文件的 image_path 相關設定）
  

除錯的萬用招：記錄面板

1.   log_level: info
2.   console_log_level: info

複製代碼

• log_level —— 顯示在卡片下方的面板裡
  
• console_log_level —— 輸出到瀏覽器的開發者工具（F12 → Console）
  

兩個都開著，你會看到 ha-floorplan 到底在做什麼 ——
載入了哪些元素、哪些規則被觸發、哪些找不到。

這個面板救過我很多次。

---

下一篇：CSS 動畫實戰 ——
燈會漸亮、門會真的轉開、風扇會轉。

這是 SVG 版本真正的價值所在。