待辦清單與行事曆

為什麼要學這個

你家現在的情況大概是這樣：媽媽在冰箱門上貼便利貼、你在手機備忘錄記東西、爸爸把繳費單塞在鞋櫃上。三個地方，三份資料，最後全部忘記。

Home Assistant 內建兩種東西可以收掉這個混亂：

• 待辦清單（To-do list）—— 一堆「要做但還沒做」的事，可以打勾，可以設到期日。購物清單就是它的一種。
• 行事曆（Calendar）—— 有明確時間的事件，垃圾車幾點來、會議幾點開、下週三要繳費。

把它們搬進 HA 最大的好處不是「看得到」，而是它們能當自動化的原料。行事曆上寫「倒垃圾 19:30」，HA 就能在 19:10 把玄關燈打開、推播到你手機；待辦清單被人加了東西，HA 就能通知全家。這是紙本便利貼永遠做不到的。

讀完這章你會有：一份全家共用的購物清單、一份本地行事曆、至少三條「行事曆一到時間就自己動」的自動化，以及一張儀表板上看得到今天要做什麼的頁面。

待辦清單 vs 行事曆：什麼時候用哪個

很多人一開始會把兩個搞混，把「倒垃圾」放進待辦清單，然後發現它不會自己提醒。判斷方法很簡單：這件事有沒有「幾點幾分」？

還有一個名詞要先講清楚：領域（Domain）。HA 把實體依照類型分成 light、switch、sensor 這些領域，待辦清單的領域叫 todo，行事曆的領域叫 calendar。所以你之後會看到 todo.shopping_list、calendar.trash_day 這種實體 ID。領域圖鑑在第 12 章。

動手一：建立第一份本地待辦清單

我們要用的整合叫 Local To-do（本地待辦清單）。「本地」的意思是資料完全存在你自己的 HA 裡，不上任何雲端，斷網也能用，也會跟著第 9 章的備份一起被帶走。

1. 打開整合頁

   左邊側欄按 設定 → 裝置與服務，確認在最上面的「整合」分頁。

2. 新增整合

   右下角的 「+ 新增整合」按鈕按下去，在搜尋框打「Local」或「待辦」，選 Local to-do（本地待辦清單）。這個整合是 Home Assistant 2023.11 加進來的，版本太舊會找不到。

   

3. 只要填一個欄位：清單名稱

   這個整合的設定畫面非常乾淨，只問你一件事——這份清單要叫什麼。打「家務」或「購物」都可以。按送出，清單就生出來了。

4. 想要幾份就再做幾次

   Local To-do 一次只建一份清單。想要「家務」「購物」「爸媽交代」三份，就重複第 2～3 步三次。每一份都會變成一個獨立的 todo. 實體。

5. 去側欄找「待辦清單」面板

   建好之後，HA 左邊側欄會出現一個待辦清單的專屬面板。點進去就能直接打字新增項目、打勾完成、設到期日。這個面板是 HA 內建的，不用你自己做儀表板。

   

6. 確認實體 ID

   到設定 → 工具 → 狀態，在篩選框打 todo.，你會看到剛剛建的清單。狀態欄的那個數字，就是這份清單目前還沒完成的項目數量。把實體 ID 抄下來，後面自動化要用。

購物清單（Shopping List）該用哪一個

HA 另外有一個叫 Shopping list（購物清單）的整合，年紀比 Local To-do 大很多。新手常問：這兩個到底差在哪、要用哪個？

兩個整合目前都還在官方文件裡、都沒有被標記淘汰。建議這樣選：

• 你只是想要一份買菜清單，而且很想用語音喊「加醬油到購物清單」 → 裝 Shopping list。
• 你想要多份清單、想要到期日、想寫比較複雜的自動化 → 用 Local to-do。
• 兩個都裝也完全沒問題，它們互不干擾。

Shopping list 有它自己的一組動作，這裡列出來讓你看得懂別人的舊教學，但寫新的自動化請一律用下一節的 todo.*，因為那組動作對所有待辦清單都通用：

shopping_list.add_item
shopping_list.complete_item
shopping_list.incomplete_item
shopping_list.remove_item
shopping_list.complete_all
shopping_list.incomplete_all
shopping_list.clear_completed_items
shopping_list.sort

todo 這個 domain 的動作速查

先講一個很重要的用詞更新：以前 HA 叫「服務（Service）」、YAML 裡寫 service:，現在一律叫「動作（Action）」、YAML 裡寫 action:。你在網路上看到 service: todo.add_item 的教學，那是舊寫法。

新增一個項目

action: todo.add_item
target:
  entity_id: todo.family_chores
data:
  item: 換客廳冷氣濾網
  due_date: "2026-09-01"
  description: 拆下來用水沖乾淨，陰乾一天再裝回去

把項目打勾（標記完成）

action: todo.update_item
target:
  entity_id: todo.family_chores
data:
  item: 換客廳冷氣濾網
  status: completed

status 只吃兩個值：needs_action（還沒做）和 completed（做完了）。想把做完的事「反悔」變回未完成，就把 status 改成 needs_action。

讀出清單內容

這個動作跟其他的不一樣，它會回傳資料，所以要搭配 response_variable 把結果存進一個變數：

action: todo.get_items
target:
  entity_id: todo.family_chores
data:
  status: needs_action
response_variable: my_items

status 不寫的話預設是 needs_action；要一次抓全部就寫成清單 [needs_action, completed]。回傳的資料長這樣：

todo.family_chores:
  items:
    - summary: 換客廳冷氣濾網
      uid: "01244b28-e604-11ee-a0a4-e45f0197c057"
      status: needs_action
      due: "2026-09-01"
      description: 拆下來用水沖乾淨
    - summary: 繳管理費
      uid: "ae993df4-e604-11ee-a0a4-e45f0197c057"
      status: needs_action

注意每個項目的欄位名稱：summary（不是 item）、uid、status，另外還有兩個選配的 due（到期日）和 description。

用待辦清單的變動當觸發

比較新的 HA 版本幫 todo 加了三個專屬觸發，在自動化編輯器裡選觸發時可以找到：

YAML 寫法跟一般觸發不太一樣，它用 target: 而不是直接寫 entity_id:：

alias: 購物清單有人加東西就通知
triggers:
  - trigger: todo.item_added
    target:
      entity_id: todo.shopping_list
actions:
  - action: notify.mobile_app_my_phone
    data:
      title: 購物清單更新
      message: 有人加了新東西，出門前記得看一下

觸發時可以拿到的資料是清單的 entity_id 和被影響的項目 ID（item_ids）。想知道到底加了什麼名字，通常要在動作裡再呼叫一次 todo.get_items 去查。

動手二：建立本地行事曆

接下來換行事曆。跟 Local To-do 一樣，官方有一個完全在地端跑的 Local Calendar（本地行事曆），是 Home Assistant 2022.12 加入的整合，資料存在你自己的 HA 設定目錄裡，不需要任何帳號、任何雲端。

1. 新增整合

   設定 → 裝置與服務 → + 新增整合，搜尋 Local calendar（本地行事曆）。

2. 取一個行事曆名稱

   照畫面指示填入行事曆名稱。建議依用途分開建，不要全部塞一個：「倒垃圾」「家事輪值」「繳費」「家具保養」各建一個。理由在下一步。

3. 為什麼要分開建：因為觸發是綁「整個行事曆」的

   行事曆觸發沒辦法說「只有標題含某字才觸發」——它是這個行事曆任何事件開始就跳。所以把不同用途分成不同行事曆，自動化才乾淨。（真的想在同一個行事曆內分辨，就在自動化裡加條件去比對 trigger.calendar_event.summary。）

4. 去側欄的「行事曆」面板加事件

   建好之後左邊側欄會有行事曆面板。點某一天就能新增事件，可以設全天事件、設起訖時間，也可以設重複（每週、每月之類）。倒垃圾這種每週固定的，就設成重複事件，設一次用一整年。

   

5. 確認實體 ID 與狀態

   設定 → 工具 → 狀態，篩選 calendar.。行事曆實體的狀態只有兩種：on 代表現在正好在某個事件進行中，off 代表沒有。

行事曆事件也可以用自動化自己生出來，這在「訂了餐廳就順手記進行事曆」這種情境很好用：

action: calendar.create_event
target:
  entity_id: calendar.family
data:
  summary: 家庭聚餐
  start_date_time: "2026-09-20 18:00:00"
  end_date_time: "2026-09-20 20:00:00"
  location: 阿嬤家

summary（標題）是唯一必填的。時間有三種指定方式，三選一：

接 Google Calendar 與 CalDAV

本地行事曆的缺點很明顯：手機上看不到。如果你全家已經在用 Google 日曆，把它接進 HA 會方便很多——在手機 Google 日曆上新增一格「倒垃圾」，HA 那邊就吃得到。

Google Calendar

老實說，這是這一章最麻煩的一步，而且麻煩不在 HA 這邊，是在 Google 那邊。HA 官方文件明講：你必須自己去 Google Cloud 開一個專案、啟用 Google Calendar API、產生一組 OAuth 用戶端憑證（Client ID 和 Client Secret），再把這組憑證貼回 HA。沒有捷徑，HA 不提供公用憑證。

接好之後，你 Google 帳號「我的日曆」底下每一個日曆，都會變成一個 calendar. 實體。它也提供一個專屬動作 google.create_event 用來新增事件。

CalDAV（Nextcloud、iCloud、Synology…）

如果你用的是 Nextcloud、Baikal、ownCloud、Synology Calendar 或 Apple iCloud，走 CalDAV 這個標準協定。官方文件說明，只要符合 RFC 4791 的伺服器基本上都能接。

主要欄位有 url（你日曆的完整網址）、username、password，另外還有 calendars / custom_calendars 可以只挑特定日曆，以及 verify_ssl（預設 true，自簽憑證的自架伺服器才需要關掉）。還有一個 days（預設 1）決定往後抓幾天的事件，它只在 custom_calendars 底下才有用，很多人寫在外層然後納悶為什麼沒效果。

Google Tasks（待辦清單，不是行事曆）

順帶一提，Google 的待辦事項也有官方整合叫 Google Tasks（Home Assistant 2023.11 加入），會把你的 Google 工作清單變成 todo. 實體。有兩個限制要先知道：

• 只支援到期「日」，不支援到期「時間」——這是 Google Tasks API 本身的限制，不是 HA 的問題。
• 它是輪詢（polling）的，官方文件寫的更新週期是每 30 分鐘。你在手機 Google Tasks 上加一項，HA 這邊不會立刻看到，要等下一次抓取。

設定方式跟 Google Calendar 一樣要自建 Google Cloud 憑證，只是要啟用的是 Google Tasks API。

把清單和行事曆放上儀表板

側欄的內建面板已經很好用，但如果你想做一頁「早上起床看一眼就知道今天要幹嘛」的儀表板，就要用卡片。儀表板編輯的基本操作在第 6 章，這裡只講這兩張卡。

1. 進入編輯模式

   打開你的儀表板，右上角鉛筆圖示進入編輯模式，然後按「+ 新增卡片」。

2. 加待辦清單卡片

   在卡片清單裡找 To-do list（待辦清單），選你的 todo. 實體。

3. 加行事曆卡片

   再新增一張，找 Calendar（行事曆）。這張卡可以一次選好幾個行事曆疊在一起顯示，不同行事曆會用不同顏色區分。

4. 用 YAML 微調

   卡片編輯視窗左下角有「顯示程式碼編輯器」，切過去就能貼下面的設定。

待辦清單卡片

type: todo-list
entity: todo.family_chores
title: 這週家務
hide_completed: true
display_order: duedate_asc

另外一個很好用但常被忽略的是 due_date_period：它讓卡片只顯示「這個範圍內到期」的項目。想做一張「今天要做的事」的卡，就這樣寫：

type: todo-list
entity: todo.family_chores
title: 今天要做
hide_completed: true
due_date_period:
  calendar:
    period: day

把 period 換成 week 就變成「這週要做的事」。offset 是往前或往後推幾個週期，例如 period: week 配 offset: 1 就是下一週。

行事曆卡片

type: calendar
title: 這個月
entities:
  - calendar.trash_day
  - calendar.family_chores
  - calendar.bills
initial_view: listWeek

用行事曆事件觸發自動化

這是整章最有價值的一節。行事曆觸發的完整寫法就這幾行：

triggers:
  - trigger: calendar
    entity_id: calendar.trash_day
    event: start
    offset: "-00:20:00"

事件的內容可以直接拿來用

觸發之後，那格事件的資料會放在 trigger.calendar_event 底下，可以直接寫進通知訊息：

整天事件的 start 只有日期沒有時間，有時間的事件則會帶時區。想從裡面取出日期部分，最簡單的寫法是切前 10 個字：{{ trigger.calendar_event.start[:10] }}。

六個馬上能抄的實用情境

下面每一段都可以直接貼進自動化編輯器的 YAML 模式（右上角三個點 → 編輯 YAML）。記得把實體 ID 換成你自己的。

一、倒垃圾日提醒

先在 Local Calendar 建一個叫「倒垃圾」的行事曆，把垃圾車時間設成每週重複事件。

alias: 垃圾車快到了
triggers:
  - trigger: calendar
    entity_id: calendar.trash_day
    event: start
    offset: "-00:20:00"
actions:
  - action: notify.mobile_app_my_phone
    data:
      title: 20 分鐘後垃圾車
      message: "{{ trigger.calendar_event.summary }}｜袋子拿了嗎"
  - action: light.turn_on
    target:
      entity_id: light.entrance
    data:
      brightness_pct: 80
mode: single

玄關燈亮起來這一招比推播更有用——推播會被忽略，但走過去看到燈亮著會想起來。

二、繳費日：到期日一到就提醒

這個情境用待辦清單而不是行事曆，因為繳費是「還沒做完就一直存在」的事。做法是每天早上八點掃一次清單，看有沒有今天到期的：

alias: 今天到期的待辦提醒
triggers:
  - trigger: time
    at: "08:00:00"
actions:
  - action: todo.get_items
    target:
      entity_id: todo.family_chores
    data:
      status: needs_action
    response_variable: result
  - variables:
      today: "{{ now().date() | string }}"
      due_today: >-
        {{ result['todo.family_chores']['items']
           | selectattr('due', 'defined')
           | rejectattr('due', 'none')
           | selectattr('due', 'search', today)
           | map(attribute='summary') | list }}
  - if:
      - condition: template
        value_template: "{{ due_today | count > 0 }}"
    then:
      - action: notify.mobile_app_my_phone
        data:
          title: 今天有 {{ due_today | count }} 件事到期
          message: "{{ due_today | join('、') }}"
mode: single

中間那三行過濾是整段的關鍵，一行一個任務：selectattr('due', 'defined') 先把「連 due 這個欄位都沒有」的項目挑掉，rejectattr('due', 'none') 再把有欄位但值是空的挑掉，最後 selectattr('due', 'search', today) 才留下到期日字串裡含今天日期的。少了前兩關，只要清單裡有一項沒設到期日，整條自動化就會報範本錯誤。

三、冷氣濾網更換：行事曆生出待辦

經典的「行事曆 + 待辦」組合技。行事曆負責記時間週期，時間一到就自動塞一條待辦進清單，你什麼時候有空什麼時候做，做完打勾：

alias: 保養行事曆自動生待辦
triggers:
  - trigger: calendar
    entity_id: calendar.maintenance
    event: start
actions:
  - action: todo.add_item
    target:
      entity_id: todo.family_chores
    data:
      item: "{{ trigger.calendar_event.summary }}"
      due_date: "{{ trigger.calendar_event.start[:10] }}"
      description: "{{ trigger.calendar_event.description }}"
mode: queued
max: 10

在「保養」行事曆裡設幾個每三個月重複的整天事件：「洗客廳冷氣濾網」「換淨水器濾芯」「清洗洗衣機」。設一次，之後每季自動出現在待辦清單裡。

四、家事輪值

在「家事輪值」行事曆裡，把事件標題直接寫成「這週輪到小明洗碗」，然後：

alias: 家事輪值提醒
triggers:
  - trigger: calendar
    entity_id: calendar.chore_rotation
    event: start
    offset: "-01:00:00"
actions:
  - action: todo.add_item
    target:
      entity_id: todo.family_chores
    data:
      item: "{{ trigger.calendar_event.summary }}"
  - action: notify.family_all
    data:
      title: 家事輪值
      message: "一小時後：{{ trigger.calendar_event.summary }}"
mode: queued
max: 10

notify.family_all 是把全家手機打包成一個通知群組的做法，設定方式在第 7 章。

五、辦公室會議室：一格事件管燈跟冷氣

小型辦公室最實用的一條。把會議室預約行事曆接進 HA（Google Calendar 或 CalDAV 都可以），開會前十分鐘先把燈跟冷氣打開，散會就關掉：

alias: 會議室隨預約開關
triggers:
  - trigger: calendar
    id: meeting_start
    entity_id: calendar.meeting_room
    event: start
    offset: "-00:10:00"
  - trigger: calendar
    id: meeting_end
    entity_id: calendar.meeting_room
    event: end
actions:
  - choose:
      - conditions:
          - condition: trigger
            id: meeting_start
        sequence:
          - action: light.turn_on
            target:
              entity_id: light.meeting_room
          - action: climate.turn_on
            target:
              entity_id: climate.meeting_room
      - conditions:
          - condition: trigger
            id: meeting_end
        sequence:
          - action: light.turn_off
            target:
              entity_id: light.meeting_room
          - action: climate.turn_off
            target:
              entity_id: climate.meeting_room
mode: queued
max: 10

這裡示範了一個好習慣：一條自動化用 id 區分多個觸發，再用 choose 分岔，比拆成兩條分開維護清楚。冷氣如果不吃 climate.turn_on，改用 climate.set_hvac_mode，各 domain 的控制方式看第 12 章。

六、每週把打勾的清掉

alias: 週日晚上清空已完成
triggers:
  - trigger: time
    at: "22:00:00"
conditions:
  - condition: time
    weekday:
      - sun
actions:
  - action: todo.remove_completed_items
    target:
      entity_id: todo.family_chores
mode: single

串起通知與語音助理

通知：讓提醒真的被看到

上面所有情境的最後一哩路都是通知，而通知的完整設定（Companion App 安裝、notify.mobile_app_* 實體名稱怎麼查、通知群組）在第 7 章，這裡不重複。只補三個跟待辦／行事曆特別搭的技巧：

• 把事件標題直接放進訊息——用 {{ trigger.calendar_event.summary }}，一條自動化就能服務行事曆上所有事件，不用一個事件寫一條。
• 加條件避免半夜吵人——在 conditions: 加時間條件，或加「有人在家」的條件。整天在外面的時候收到「垃圾車來了」只會讓人想關通知。
• 通知不只手機——會議室情境裡，把燈閃兩下或用語音播報，比推播有效得多。

語音：用喊的加購物清單

語音助理是這一章的天然搭檔——手上沾著油、冰箱門開著的時候，喊一句比掏手機快多了。這部分的重點：

• Shopping list 整合的官方文件明確提到可以用語音指令加東西，例句是英文的「Add eggs to my shopping list」。
• 中文句型不保證開箱即用。HA 的內建語音句型各語言的完整度不一樣，你的版本、你的語音助理設定都會影響結果。想確認自己這套行不行，最快的方法是打開 HA 右上角的 Assist 對話框，直接打字（不用講）試一句，看它有沒有反應。
• 如果內建句型不吃你想講的話，退路是自訂句子（custom sentences），把你習慣的講法對應到 todo.add_item。設定方式請看語音助理那一章。

常見卡關

1. Google 授權每 7 天就掉一次，一直叫我重新登入

   這幾乎百分之百是 OAuth 同意畫面停在 Testing（測試中）。官方文件明確警告這個狀態下憑證每 7 天過期。回 Google Cloud Console 的 OAuth 同意畫面，按 Publish app 把發布狀態改掉，再回 HA 重新授權一次。改完之後就不會再掉了。

2. Google 授權當下就失敗，跳「redirect_uri_mismatch」或類似錯誤

   意思是你在 Google 那邊登記的重新導向網址，跟 HA 實際送出的對不起來。照官方文件指定的重新導向網址一字不差填進 Google 憑證設定，中英文大小寫、結尾有沒有斜線都算數。另外檢查有沒有把 Google Calendar API 啟用——很多人建了憑證卻忘了啟用 API。

3. 事件時間整個差幾小時（時區錯位）

   這是第二常見的坑，而且有三個地方都可能出錯，要一個一個排：
   (1) HA 本身的時區——去 設定 → 系統 → 家庭資訊，在「地區（Region）」那一區確認時區是不是 Asia/Taipei。如果欄位是灰的改不動，代表它被寫死在 configuration.yaml 裡，要先把那行拿掉。這在第 2 章講過。
   (2) 來源行事曆的時區——Google 日曆本身有一個日曆時區設定，如果那邊是別的時區，整組事件都會偏。
   (3) 整天事件——整天事件本來就沒有時刻，all_day 會是 true，start 只有日期。拿它去跟時間比較一定怪，要先判斷 all_day 再決定怎麼處理。

4. 行事曆自動化該跳的時候沒跳

   先想「我是多久前才建這個事件的？」官方文件寫明行事曆每 15 分鐘才讀一次。剛建好就要在 5 分鐘後觸發，來不及是正常的。第二個常見原因是 offset 寫錯——提前一定要有負號，"-00:30:00" 是提前半小時，"00:30:00" 是延後半小時。第三，去設定 → 自動化與場景點開那條自動化，右上角三個點 → 追蹤（Traces），看它到底有沒有被觸發、卡在哪一步。

5. 待辦清單同步不同步、手機上加的東西 HA 看不到

   先分清楚你用的是哪一種：Local To-do 沒有同步問題，因為它只存在 HA 裡，沒有別的地方跟它同步。會有同步落差的是雲端來源——Google Tasks 官方文件寫的是每 30 分鐘輪詢一次，CalDAV 也是定期抓取。所以「手機加了 HA 沒看到」通常不是壞掉，是還沒到下次抓取時間。真的等太久還是沒有，去設定 → 裝置與服務找到該整合，三個點 → 重新載入，強迫它抓一次。

6. todo.update_item 說找不到項目

   三個方向：(1) 名字要完全一樣，多一個空白、全形半形不同都算不一樣；(2) 清單裡有兩個同名項目，HA 不知道要改哪個，改用 uid——先用 todo.get_items 撈出 UID，再把 UID 填進 item 欄位；(3) 你打錯 entity_id，改到另一份清單去了。

7. 加項目時報錯，說到期日的參數有問題

   最常見是due_date 和 due_datetime 同時寫了，這兩個只能二選一。第二種是你用的那份清單根本不支援到期日或描述——不是每個整合都支援全部欄位，例如 Google Tasks 就只支援日期不支援時間。拿掉那個參數再試一次就知道是不是這個原因。

8. 刪掉整合之後，待辦清單面板一直報錯

   儀表板上的卡片還指著已經不存在的實體。去編輯模式把那張孤兒卡片刪掉。刪整合前先想一下有沒有哪張卡片、哪條自動化在用它，這個習慣可以省很多事。

常見問題