2025.3.4
首页 ▸ Integrations ▸

To-do list

The To-do list integration集成将 Home Assistant 与您的设备、服务等连接和集成。 [Learn more] provides to-do list entities实体表示 Home Assistant 中的传感器、执行器或功能。实体用于监控物理属性或控制其他实体。实体通常是设备或服务的一部分。 [Learn more], allowing other integrations to integrate to-do lists into Home Assistant. To-do lists are shown on the To-do lists dashboard for tracking items and whether or not they have been completed.

Note

构建模块集成

这个 to-do list 是一个构建模块集成，无法直接添加到你的 Home Assistant 中，但可以被其他集成使用和提供。

构建模块集成不同于典型的与设备或服务连接的集成。相反，其他将设备或服务集成到 Home Assistant 中的集成使用这个 to-do list 构建模块来提供实体、服务和其他你可以在自动化或仪表板中使用的功能。

如果你的某个集成具有这个构建模块，这个页面记录了 to-do list 构建模块所提供的功能。

For example, Local to-do is a fully local integration to create to-do lists and tasks within your Home Assistant instance, Shopping list specifically for shopping that can be added to with Assist, or other integrations work with online services providing to-do list data.

Viewing and managing to-do lists

Each to-do list is represented as its own entity in Home Assistant and can be viewed and managed on a to-do list dashboard. You can find the to-do list dashboard in the main sidebar of your Home Assistant instance.

The state of a to-do list entity

The state of a to-do list entity is a number, which represents the number of incomplete items in the list.

Screenshot showing the state of a to-do list entity in the developer tools Screenshot showing the state of a to-do list entity in the developer tools.

In addition, the entity can have the following states:

  • Unavailable: The entity is currently unavailable.
  • Unknown: The state is not yet known.

Blueprint to add an item to a dedicated list

This blueprint allows you to create a script to add an item to a pre-configured to-do list.

Actions

Some to-do list integrations allow Home Assistant to manage the to-do items in the list. The actions provided by some to-do list entities are described below or you can read more about actions.

Action todo.get_items

Get to-do items from a to-do list. A to-do list target is selected with a target selector. The data payload supports the following fields:

Data attribute Optional Description Example
status yes Only return to-do items with this status. needs_action, completed

This is a full example that returns all to-do items that have not been completed:

action: todo.get_items
target:
  entity_id: todo.personal_tasks
data:
  status:
    - needs_action

Action todo.add_item

Add a new to-do item. A to-do list target is selected with a Target Selector and the data payload supports the following fields:

Data attribute Optional Description Example
item no The name/summary of the to-do item. Submit income tax return
due_date yes The date the to-do item is expected to be completed. 2024-04-10
due_datetime yes The date and time the to-do item is expected to be completed. 2024-04-10 23:00:00
description yes A more complete description than the one provided by the summary. Collect all necessary documents and submit the final return.

Only one of due_date or due_datetime may be specified.

This is a full example in YAML:

action: todo.add_item
target:
  entity_id: todo.personal_tasks
data:
  item: "Submit Income Tax Return"
  due_date: "2024-04-10"
  description: "Collect all necessary documents and submit the final return."

Action todo.update_item

Update a to-do item. A to-do list target is selected with a Target Selector and the data payload supports the following fields:

Data attribute Optional Description Example
item no The name/summary of the to-do item to update. Submit income tax return
rename yes The new name of the to-do item. Something else
status yes The overall status of the to-do item. needs_action or completed
due_date yes The date the to-do item is expected to be completed. 2024-04-10
due_datetime yes The date and time the to-do item is expected to be completed. 2024-04-10 23:00:00
description yes A more complete description than the one provided by the summary. Collect all necessary documents and submit the final return.

At least one of rename or status is required. Only one of due_date or due_datetime may be specified. This is a full example that updates the status and the name of a to-do item.

action: todo.update_item
target:
  entity_id: todo.personal_tasks
data:
  item: "Submit income tax return"
  rename: "Something else"
  status: "completed"

Action todo.remove_item

Removing a to-do item. A to-do list target is selected with a Target Selector, and the data payload supports the following fields:

Data attribute Optional Description Example
item no The name of the to-do item. Submit income tax return

This is a full example that deletes a to-do Item with the specified name.

action: todo.remove_item
target:
  entity_id: todo.personal_tasks
data:
  item: "Submit income tax return"

Action todo.remove_completed_items

Removes all completed to-do items. A to-do list target is selected with a Target Selector.

This is a full example that deletes all completed to-do items.

action: todo.remove_completed_items
target:
  entity_id: todo.personal_tasks

相关主题