自己寫 HA 藍圖：把自動化變成可以重複用的模板

charles

藍圖（Blueprint）就是「留空格的自動化」。

寫一次，之後每個房間填不同的實體，點幾下就建好。



什麼時候該做藍圖

訊號很明確：你複製貼上了同一個自動化第三次。

典型的例子：

• 每個房間都要一個「有人開燈、沒人關燈」
  
• 每個門磁都要一個「開超過五分鐘通知」
  
• 每個無線按鈕都要一組「單擊、雙擊、長按」
  

先用現成的

自己寫之前先去看有沒有人做好了。

• 設定 → 自動化與場景 → 藍圖 → 匯入藍圖
  
• 貼上網址就會下載
  

找藍圖的地方：

• HA 官方論壇的 Blueprints Exchange 版（最多）
  
• GitHub 搜 "home assistant blueprint"
  
• 社群整理的收錄站
  

熱門的藍圖：

• Motion-activated Light —— 人體感應燈（官方內建就有）
  
• ZHA / Z2M 各種遙控器的按鍵對應
  
• Sensor Light —— 功能很完整的感應燈（考慮了亮度、時段、手動覆蓋）
  

藍圖的結構

放在 config/blueprints/automation/你的名字/

1. blueprint:
2.   name: 感應燈（我的版本）
3.   description: 有人開燈，沒人 N 分鐘後關燈
4.   domain: automation
5.   input:
6.     動作感測器:
7.       name: 人體感應器
8.       selector:
9.         entity:
10.           filter:
11.             domain: binary_sensor
12.             device_class: motion
14.     目標燈:
15.       name: 要控制的燈
16.       selector:
17.         target:
18.           entity:
19.             domain: light
21.     等待時間:
22.       name: 沒人多久關燈
23.       default: 120
24.       selector:
25.         number:
26.           min: 10
27.           max: 3600
28.           unit_of_measurement: 秒
30. mode: restart
31. max_exceeded: silent
33. triggers:
34.   - trigger: state
35.     entity_id: !input 動作感測器
36.     from: "off"
37.     to: "on"
39. actions:
40.   - action: light.turn_on
41.     target: !input 目標燈
42.   - wait_for_trigger:
43.       - trigger: state
44.         entity_id: !input 動作感測器
45.         from: "on"
46.         to: "off"
47.   - delay:
48.       seconds: !input 等待時間
49.   - action: light.turn_off
50.     target: !input 目標燈

複製代碼

三個重點

一、!input 名稱

這是佔位符 —— 使用者在介面上填什麼，這裡就換成什麼。

二、selector 決定介面長什麼樣



常用的 selector：

1. selector:
2.   entity:                    選一個實體
3.     filter:
4.       domain: light
6.   target:                    選實體 / 裝置 / 區域（比 entity 彈性）
7.     entity:
8.       domain: light
10.   number:                    數字滑桿
11.     min: 0
12.     max: 100
13.     step: 5
14.     unit_of_measurement: "%"
16.   boolean:                   開關
18.   time:                      時間選擇器
20.   select:                    下拉選單
21.     options:
22.       - 選項 A
23.       - 選項 B
25.   text:                      文字輸入
26.     multiline: true
28.   action:                    讓使用者自己填一段動作
30.   duration:                  時間長度（時分秒）
32.   device:                    選一個裝置
33.     filter:
34.       integration: zha

複製代碼

selector 選對的話，介面會很好用；
選錯的話使用者要自己打實體 ID。

target vs entity

• entity —— 只能選單一實體
  
• target —— 可以選多個實體、整個裝置、整個區域
  

控制燈的話用 target 比較好，
使用者可以直接選「客廳」這個區域。

三、default 讓它可以不填

1.     等待時間:
2.       name: 沒人多久關燈
3.       default: 120

複製代碼

有 default 的欄位是選填的。

進階：讓使用者自訂動作



這招很強：

1.   input:
2.     按鈕:
3.       name: 無線按鈕
4.       selector:
5.         device:
6.           filter:
7.             integration: mqtt
9.     單擊動作:
10.       name: 單擊時做什麼
11.       default: []
12.       selector:
13.         action:
15.     雙擊動作:
16.       name: 雙擊時做什麼
17.       default: []
18.       selector:
19.         action:
21. actions:
22.   - choose:
23.       - conditions:
24.           - condition: template
25.             value_template: "{{ trigger.payload_json.action == 'single' }}"
26.         sequence: !input 單擊動作
28.       - conditions:
29.           - condition: template
30.             value_template: "{{ trigger.payload_json.action == 'double' }}"
31.         sequence: !input 雙擊動作

複製代碼

這樣使用者可以在介面上直接編輯「單擊要做什麼」，
不用改藍圖。

幾乎所有遙控器藍圖都是這樣做的。

讓藍圖更好用的細節

一、加 description 說明

1. blueprint:
2.   name: 感應燈
3.   description: >
4.     有人的時候開燈，沒人 N 分鐘後關燈。
6.     ## 注意事項
7.     - 手動關燈之後，下次有人還是會開
8.     - 建議搭配 mode: restart

複製代碼

description 支援 Markdown，會顯示在介面上。

二、用 collapsed 收納進階選項

1.   input:
2.     基本設定:
3.       name: 基本設定
4.       icon: mdi:cog
5.       collapsed: false
6.       input:
7.         感應器: ...
8.         目標燈: ...
10.     進階設定:
11.       name: 進階設定
12.       icon: mdi:tune
13.       collapsed: true
14.       input:
15.         亮度: ...
16.         過渡時間: ...

複製代碼

把選項分組，進階的預設收起來 —— 介面清爽很多。

三、加條件讓使用者選擇性啟用

1.     只在天黑時:
2.       name: 只在天黑時動作
3.       default: true
4.       selector:
5.         boolean:
7. conditions:
8.   - condition: template
9.     value_template: >
10.       {{ not 只在天黑 or is_state('sun.sun', 'below_horizon') }}
12. variables:
13.   只在天黑: !input 只在天黑時

複製代碼

注意：!input 不能直接寫在模板裡 ——
要先用 variables 接一層。

這是最多人踩的坑。

除錯

藍圖改了沒生效

• 設定 → 開發者工具 → YAML → 重新載入藍圖
  
• 或者重啟 HA
  

藍圖載入失敗

• 看日誌 —— 通常是 YAML 縮排錯誤
  
• 檢查 !input 的名稱有沒有跟 input 區塊對上（大小寫要一樣）
  

建了自動化但沒反應

• 去自動化的「追蹤」看 —— 會顯示卡在哪一步
  
• 檢查 mode 設定（感應燈一定要 restart）
  

分享你的藍圖

• 把 YAML 檔放到 GitHub（可以用 Gist）
  
• 拿到 raw 網址
  
• 別人貼那個網址就能匯入
  
• 發到 HA 論壇的 Blueprints Exchange
  

HA 還提供「我的 HA」連結產生器，
可以做出一個「匯入藍圖」的漂亮按鈕。

---

下一篇：腳本（Script）與場景（Scene） ——
什麼時候該用哪個，以及怎麼組合它們。