腳本 Scripts

為什麼需要腳本

當你發現自己在很多個自動化裡重複貼同一段動作，例如：

• 「關全家燈 + 冷氣關 + 掃地機開始 + 玄關燈延遲 30 秒關」— 出門情境
• 「所有窗簾拉起 + 主燈 20% + 音響播早安歌單」— 起床情境
• 「主臥燈慢慢淡到 5% 再關」— 睡覺淡出

直接把這一整段包成一個腳本，例如 script.leaving_home，之後：

• 離家自動化 → 只要「呼叫 script.leaving_home」一行
• 玄關 Zigbee 按鈕長按 → 也呼叫 script.leaving_home
• 語音助理說「我要出門了」→ 也呼叫 script.leaving_home
• 儀表板放一顆大按鈕 → 也呼叫 script.leaving_home

之後你想改「出門要不要順便關飲水機」，只改腳本這一個地方，四個入口全部同步。這就是把邏輯集中的價值。

腳本 vs 自動化 vs 場景

三個名詞新手常混淆，先分清楚：

• 自動化 Automation：三段式（觸發／條件／動作），會「自己啟動」。例：日落時觸發。
• 腳本 Script：只有動作段，不會自己啟動，要被叫。可以有延遲、迴圈、條件分支，比場景強大很多。
• 場景 Scene：一組實體「狀態快照」（燈 60% / 冷氣 26°C / 窗簾 100%）。呼叫時瞬間把所有實體切到指定狀態。不能有延遲或邏輯。

動手做：第一個腳本「離家模式」

1. 設定 → 自動化與場景 → 腳本頁籤

   右下角「＋ 新增腳本」→ 選「建立新腳本」。（如果選「從藍圖」也可，但先從空白開始。）

   

2. 填寫名稱與 icon

   名稱：「離家模式」
   Icon：mdi:door-open（可從 pictogrammers.com 找）
   頁面下方會自動生成 entity_id：script.leaving_home。這個 ID 之後用來呼叫，取個好記的名字。

3. 加動作：關掉所有燈

   「＋ 新增動作」→「執行動作」（舊版叫「呼叫服務」）→ 選 light.turn_off。
   目標：不要一顆一顆選；用「區域」選「全部」，或用「標籤」（第 4 章教的）選「燈光」。這樣之後新加的燈會自動被涵蓋。

   

4. 加動作：關冷氣

   「＋ 新增動作」→ climate.turn_off → 目標選所有 climate 實體或用「冷氣」標籤。

5. 加動作：等 30 秒

   「＋ 新增動作」→「延遲」→ 30 秒。這是腳本比場景強的地方，可以排時序。

6. 加動作：關玄關燈

   「＋ 新增動作」→ light.turn_off → 目標選玄關燈單一實體。用意：前面已經關全家燈，玄關燈延遲 30 秒才關，讓你有時間穿鞋出門。

7. 加動作：推播通知

   「＋ 新增動作」→ notify.mobile_app_你的手機（見第 7 章）→ 訊息：「離家模式已啟動 ✅」。這樣就算按錯，手機會提示你。

8. 右上角「儲存」→ 點試跑（▶）

   儲存後上方會出現橘色「儲存」變綠 → 按「執行腳本」測試。如果動作正確，手機應收到通知。

   驗證：到「設定 → 工具 → 動作」呼叫 script.leaving_home，也應該完整跑一次。同一個入口從腳本頁、設定 → 工具、儀表板、自動化叫都是等價的。

加參數（Fields）— 讓腳本可被客製

剛才的腳本寫死了「30 秒延遲」，如果晚上想 60 秒、白天想 15 秒怎麼辦？加一個 Field（欄位）：

1. 編輯腳本 → 右上「⋮」→「編輯 YAML」

   UI 也能加欄位（在腳本頁面下方「欄位」區），但 YAML 一次看得清楚。加入：

   fields:
     delay_seconds:
       name: 玄關燈延遲秒數
       description: 幾秒後關玄關燈
       default: 30
       selector:
         number:
           min: 5
           max: 300
           unit_of_measurement: 秒

2. 把動作裡的 30 改成變數

   - delay:
       seconds: "{{ delay_seconds }}"

   之後呼叫時就能傳參數：script.leaving_home + delay_seconds: 60。

3. UI 呼叫也能填欄位

   加了 fields 後，在儀表板卡片、自動化的動作、設定 → 工具呼叫這隻腳本時，會自動出現一個可以填「延遲秒數」的欄位，非工程師也能改。

執行模式 Single / Restart / Queued / Parallel

當腳本正在跑，又被叫一次會怎樣？這由「模式」決定，跟自動化一樣：

實用範例集

1. 睡覺淡出（restart 模式）

從當前亮度開始 30 秒內淡到 1%，再過 5 秒關掉。中途再按會重來。

alias: bedroom_fade_out
mode: restart
sequence:
  - action: light.turn_on
    target:
      entity_id: light.bedroom_main
    data:
      brightness_pct: 1
      transition: 30
  - delay: "00:00:35"
  - action: light.turn_off
    target:
      entity_id: light.bedroom_main

2. 迴圈通知直到有人回應（repeat until）

洗衣機洗完每 3 分鐘推播一次，直到有人到洗衣間（Zigbee 動作感應器觸發）為止。

alias: nag_until_laundry_picked
mode: restart
sequence:
  - repeat:
      until:
        - condition: state
          entity_id: binary_sensor.laundry_motion
          state: "on"
      sequence:
        - action: notify.mobile_app_dad
          data:
            message: 洗衣機洗完了，快去拿！
        - delay: "00:03:00"

3. 條件分支（choose）

回家時根據時段做不同事：白天只開空調、晚上開燈+空調、深夜只開夜燈。

alias: arriving_home
sequence:
  - choose:
      - conditions:
          - condition: sun
            before: sunset
        sequence:
          - action: climate.turn_on
            target: { entity_id: climate.livingroom }
      - conditions:
          - condition: time
            after: "23:00:00"
        sequence:
          - action: light.turn_on
            target: { entity_id: light.hallway }
            data: { brightness_pct: 20 }
    default:
      - action: light.turn_on
        target: { area_id: livingroom }
      - action: climate.turn_on
        target: { entity_id: climate.livingroom }

4. 並行動作（parallel）— 全開全關的最快版本

正常一連串動作是序列跑，用 parallel 可以同時發，快很多：

sequence:
  - parallel:
      - action: light.turn_off
        target: { area_id: livingroom }
      - action: cover.close_cover
        target: { area_id: livingroom }
      - action: media_player.turn_off
        target: { entity_id: media_player.tv }

5. 呼叫其他腳本 / 場景

sequence:
  - action: scene.turn_on
    target: { entity_id: scene.movie_night }
  - delay: "00:00:02"
  - action: script.turn_on
    target: { entity_id: script.close_all_curtains }

差別：用 script.turn_on 呼叫是「發射後不管」，主腳本繼續往下跑；直接寫 action: script.其他腳本（不加 turn_on）則是「等它跑完再繼續」。想同步等就用後者。

如何呼叫腳本（4 種入口）

1. 從自動化的動作段

   自動化 → 動作 → 選「執行動作」→ script.leaving_home（或直接選腳本 entity）。有 fields 時會顯示欄位。

2. 從儀表板卡片

   加一顆按鈕卡（Button card）→ 點擊動作選「執行動作」→ script.turn_on → 目標選腳本。想更花俏用 Tile card + 客製 icon。

3. 從 Zigbee 遙控器 / 場景面板

   用第 8 章講的「MQTT 事件」或「ZHA 事件」抓按鈕，動作段呼叫這隻腳本。長按、短按、雙擊都可映射到不同腳本。

4. 從語音助理 Assist

   「暴露 Expose」給 Assist（設定 → 語音助理 → 暴露腳本），之後可以說「Hey，離家模式」直接叫。這是內建功能，不用寫任何整合。

常見卡關

常見問題