Home Assistantcalendar.create_event动作完全指南从 UI 到 YAML 的日历写事件实战【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io导读calendar.create_event是 Home Assistant 中用于向日历实体添加新事件的核心动作action典型用途包括在自动化中为洗衣机完成、门锁打开等事件打上时间戳记录或者提前在日历上阻塞一段忙碌时间。读完本文你将掌握在自动化与脚本中通过可视化界面和 YAML 两种方式创建日历事件的完整流程理解summary、start_date_time、in、location等全部参数的含义与取值规则并能直接套用开箱即用的自动化示例。动作概览向日历写入事件在 Home Assistant 中每个日历都以独立实体entity的形式存在可以在主侧边栏的日历面板calendar dashboard上查看与管理。部分日历集成支持 Home Assistant 直接管理日历内容此时既可以在日历面板右下角点击Add event按钮手动添加事件也可以通过calendar.create_event动作在自动化与脚本中编程式地写入事件。该动作的官方描述是Adds a new event to a calendar向日历添加一个新事件隶属于calendar域domain。它专注于「写」日历与其配套的读操作是 calendar.get_events 动作后者用于在指定时间范围内读取一个或多个日历上的事件并把结果存入响应变量供后续步骤使用。与它配合最紧密的动作是 calendar.get_events一个负责把事件写入日历一个负责把事件读出来二者常在同一自动化中先后出现例如先查询某个时间段是否空闲再决定是否写入新事件。从用户界面UI创建日历事件如果你习惯用可视化方式搭建自动化Home Assistant 会一步步引导你完成操作选择目标、微调选项、保存即可全程无需编写 YAML。具体步骤如下进入设置自动化与场景Settings Automations scenes。打开现有的自动化或脚本如果是新建选择创建自动化创建新自动化Create automation Create new automation。如果是新自动化在When触发条件区域添加一个触发器脚本不需要触发器它们在被其他内容调用时运行。在Then do执行动作区域选择添加动作Add action。在按目标选择By target详见下文「动作的目标」小节下选择要添加事件的日历。从该目标可用的动作列表中选择创建日历事件Create calendar event。设置摘要Summary以及事件的开始和结束时间。点击保存Save。UI 中的选项在可视化界面中创建日历事件时可以看到以下选项选项说明是否必填Summary事件的标题必填Description比 Summary 更详细的事件描述可选Start time事件开始的日期和时间可选End time事件结束的日期和时间结束时间不包含在内即开区间可选Start date全天事件开始的日期可选End date全天事件结束的日期结束日期不包含在内即开区间可选In从现在起若干天或若干周之后创建事件可选Location事件的地点可选在 YAML 中使用该动作如果你直接编写 YAML或者想确切了解 Home Assistant 在底层做了什么本节给出完整的技术参考YAML 中的字段名、字段类型以及哪些字段是必填的。在 YAML 中该动作被引用为calendar.create_event。一个基础示例如下action: calendar.create_event target: entity_id: calendar.family data: summary: Bowling night start_date_time: 2024-03-10 20:00:00 end_date_time: 2024-03-10 23:00:00 location: Bowling center这个示例向calendar.family日历添加了一个名为 Bowling night保龄球之夜的事件。YAML 中的全部参数参数说明是否必填类型summary事件的标题是stringdescription比 summary 更详细的事件描述否stringstart_date_time事件开始的日期和时间例如2024-03-10 20:00:00否stringend_date_time事件结束的日期和时间开区间不包含例如2024-03-10 23:00:00否stringstart_date全天事件开始的日期例如2024-03-10否stringend_date全天事件结束的日期开区间不包含例如2024-03-11否stringin从现在起若干天或若干周之后创建事件例如days: 2或weeks: 2否maplocation事件的地点否string除summary外其余参数全部为可选。注意start_date_time与end_date_time的格式为YYYY-MM-DD HH:MM:SS而全天事件使用YYYY-MM-DD格式的start_date与end_date。使用in参数相对创建事件in参数让你不必手工计算未来日期而是以「相对时间」的方式创建事件类型为 map支持days与weeks两个键action: calendar.create_event target: entity_id: calendar.family data: summary: Car inspection in: days: 2也可使用周为单位data: summary: Monthly review in: weeks: 2动作的目标Targetscalendar.create_event动作必须指定目标target。目标是动作的作用对象你可以将动作指向单个实体、设备、区域、楼层或标签Home Assistant 会对目标背后每一个匹配的 calendar 实体执行该动作实体Entity某个特定的 calendar 实体例如calendar.living_room。设备Device属于某设备的所有 calendar 实体。区域Area某个房间或区域内的所有 calendar 实体。楼层Floor某个楼层上的所有 calendar 实体。标签Label共享某个标签的所有 calendar 实体。同一个动作中也可以混合选择不同类型的目标例如同时指定一个具体实体和一个区域作为目标让动作一次作用于两者。与 Calendar 集成配套使用的要点calendar.create_event建立在 Home Assistant 的 Calendar 集成 之上。该集成提供 calendar 实体使各外部日历平台可以接入 Home Assistant事件会显示在日历面板上并可用于自动化。日历实体的状态每个日历实体的状态反映其当前是否有活动事件On日历当前有活动事件。Off日历当前没有活动事件。此外还可能处于Unavailable实体当前不可用或Unknown状态未知状态。用日历触发器配合写事件值得注意的一点是如果你要「基于日历事件」触发自动化官方推荐优先使用日历触发器calendar trigger而不是基于实体状态触发因为后者仅反映下一个事件且属性有限。一个典型的日历触发器示例automation: - triggers: - trigger: calendar # 可选值start、end event: start # 日历的 entity_id entity_id: calendar.personal # 可选在事件开始/结束前或后的一段时间触发 offset: -00:15:00注意日历每 15 分钟被读取一次。测试时不要安排距离当前时间不足 15 分钟的事件否则触发器可能不会触发。日历触发器一般也不应使用自动化模式single而应使用queued或parallel以确保多个事件同时开始时都能触发。理解了「读」触发器、get_events与「写」create_event两条链路你就能构建完整的日历自动化闭环外部事件触发 → 查询/创建事件 → 通知或后续处理。三个值得记住的使用要点官方文档特别强调了以下两条规则它们直接决定事件写入是否正确设置事件时间有三种互斥方式使用开始/结束时间start_date_time/end_date_time或者使用全天事件的开始/结束日期start_date/end_date或者使用in从现在起若干天或若干周后创建。三者择一使用。事件的结束是开区间exclusive结束时间/日期不包含事件本身。因此一个发生在 2024-03-10 的全天事件其end_date应为 2024-03-11。实战示例洗衣机完成时自动记录下面是一个完整的实战自动化当洗衣机功率降为待机时在日历上记录一条事件这样你就有了洗衣历史的存档。触发器洗衣机功率变为待机idle动作创建日历事件目标Home log摘要Laundry finished洗衣完成对应的完整 YAMLautomation: alias: Log when the washing machine finishes triggers: - trigger: state entity_id: sensor.washing_machine_status to: idle actions: - action: calendar.create_event target: entity_id: calendar.home_log data: summary: Laundry finished start_date_time: 2024-03-10 18:00:00 end_date_time: 2024-03-10 18:01:00这个示例展示了calendar.create_event的典型用法用一个状态触发器捕获现实世界中的事件然后立即在日历上写入一条短暂的时间记录形成可回溯的历史档案。你可以直接复制这段 YAML替换其中的实体 ID、摘要和时间后适配到自己的环境。常见问题排查如果动作没有按预期工作可以按以下方向排查目标是否正确确认target.entity_id指向的 calendar 实体真实存在可在设置设备与服务中确认日历集成已配置。时间格式是否合法start_date_time/end_date_time使用YYYY-MM-DD HH:MM:SS全天事件用YYYY-MM-DD的start_date/end_date三者不要混用。结束时间是否合理由于结束是开区间end_date_time必须晚于start_date_time全天事件的end_date必须是start_date的次日或更晚。日历是否支持写入并非所有日历集成都允许 Home Assistant 写入事件。请确认你使用的日历集成支持事件创建可查阅对应集成文档。相关动作calendar.create_event与以下动作配合使用效果最佳Get calendar events获取指定日期范围内的日历事件。它返回响应变量可在同一自动化或脚本的后续步骤中使用例如先查询某个时间段是否已被占用再决定是否写入新事件。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考