事件组件

ESPHome 支持在 Home Assistant 中创建事件实体。这些实体允许在 Home Assistant 生态系统中触发自定义事件，实现复杂的自动化和集成。事件实体表示为与设备关联的无状态实体，具有可以触发的一组预定义事件类型。

NOTE

ESPHome 中的事件旨在触发 Home Assistant 中的动作，并具有从 ESPHome 到 Home Assistant 的单向流程。Home Assistant 事件实体与事件总线上的事件不同。如果您只想在 Home Assistant 事件总线上触发事件，应该使用 Home Assistant 事件。

NOTE

ESPHome 事件实体需要 Home Assistant Core 2024.5 或更高版本才能正常工作。

基本事件配置

ESPHome 中的每个事件都需要配置它可以触发的事件类型列表和可选的设备类别。

# 示例事件配置
event:
  - platform: ...
    name: 检测到移动事件
    id: my_event

    # 可选变量：
    icon: "mdi:motion-sensor"
    device_class: "motion"
    on_event:
      then:
        - logger.log: "事件已触发"

配置变量：

id 或 name 中必须有一个。

• id (可选, ID)：手动指定用于代码生成的 ID。必须指定 id 和 name 中的至少一个。
• name (可选, string)：事件的名称。必须指定 id 和 name 中的至少一个。

NOTE

如果您为设备设置了 friendly_name，并且希望事件使用该名称，可以设置 name: None。

• icon (可选, icon)：手动设置前端中事件使用的图标。

• internal (可选, boolean)：将此组件标记为内部组件。内部组件不会暴露给前端（如 Home Assistant）。仅指定 id 而不指定 name 会隐式将此设置为 true。

• disabled_by_default (可选, boolean)：如果为 true，则此实体不应添加到任何客户端的前端（通常是 Home Assistant），除非用户手动启用（通过 Home Assistant UI）。

• entity_category (可选, string)：实体的类别。请参阅 https://developers.home-assistant.io/docs/core/entity/#generic-properties 获取可用选项列表。设置为 "" 可移除默认实体类别。

• device_class (可选, string)：事件的设备类别。事件实体支持以下设备类别：

  • None：通用事件。这是默认值，无需设置。
  • button：用于遥控器按钮。
  • doorbell：专门用于门铃按钮。
  • motion：用于运动传感器检测到的移动事件。

  请参阅 https://www.home-assistant.io/integrations/event/#device-class 获取可用选项列表。

• 如果启用了 Webserver 并选择了版本 3，则支持 Webserver 组件的所有其他选项。请参阅 Webserver 版本 3。

自动化：

• on_event (可选, 自动化)：当触发事件时要执行的自动化。

MQTT 选项：

• MQTT 组件的所有其他选项。

事件自动化

on_event

当触发指定类型的事件时将触发此自动化。在 Lambda 中，您可以从触发器中使用 event_type 获取事件类型。

event:
  - platform: template
    # ...
    on_event:
      then:
        - lambda: |-
            ESP_LOGD("main", "事件 %s 已触发。", event_type.c_str());

配置变量：请参阅 自动化。

event.trigger 动作

此动作允许从自动化内部触发事件。

- event.trigger:
    id: my_event
    event_type: "custom_event"

配置变量：

• id (必填, ID)：事件的 ID。
• event_type (必填, string)：要触发的事件类型。

lambda 调用

在 lambda 中，您可以与事件交互。

• trigger(std::string event_type)：触发指定类型的事件。
• has_event()：如果已触发事件则返回 true，否则返回 false。
• get_last_event_type()：返回最后触发的事件类型作为 StringRef，如果尚未触发事件则返回空 StringRef。

    // 在 lambda 中，触发事件。
    id(my_event).trigger("custom_event");

    // 检查是否已触发事件
    if (id(my_event).has_event()) {
      auto event_type = id(my_event).get_last_event_type();
      // 使用 == 与字符串字面量比较
      if (event_type == "custom_event") {
        ESP_LOGD("main", "自定义事件已触发");
      }
      // 使用 %.*s 格式记录 StringRef
      ESP_LOGD("main", "最后事件：%.*s", (int) event_type.size(), event_type.c_str());
    }

另请参阅

• API Reference: event.h