Event 组件

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

NOTE

ESPHome 中的 event 旨在触发 Home Assistant 中的操作，并且具有从 ESPHome 到 Home Assistant 的单向流。 Home Assistant 的 event 实体与 event bus 上的 event 不同。如果你只想在 Home Assistant 的 event bus 上触发一个 event，应使用 Home Assistant event。

NOTE

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

基础 Event 配置

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

# 示例 event 配置
event:
  - platform: ...
    name: Motion Detected Event
    id: my_event

    # 可选变量：
    icon: "mdi:motion-sensor"
    device_class: "motion"
    on_event:
      then:
        - logger.log: "Event triggered"

配置变量：

id 和 name 必须指定其中一个。

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

NOTE

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

• icon (可选, icon)：手动设置在前端为 event 使用的图标。

• 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)：event 的设备类。event 实体支持以下设备类：

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

  参见 https://www.home-assistant.io/integrations/event/#device-class 查看可用选项列表。

• 如果启用了 Webserver 且选择了版本 3，则包含 Webserver 组件的所有其他选项。参见 Webserver 版本 3。

自动化：

• on_event (可选, Automation)：在触发 event 时执行的自动化。

MQTT 选项：

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

Event 自动化

on_event

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

event:
  - platform: template
    # ...
    on_event:
      then:
        - lambda: |-
            ESP_LOGD("main", "Event %s triggered.", event_type.c_str());

配置变量：参见 Automation。

event.trigger 操作

此操作允许在自动化内部触发 event。

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

配置变量：

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

lambda 调用

在 lambda 中，你可以与 event 进行交互。

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

    // 在 lambda 内，触发 event。
    id(my_event).trigger("custom_event");

    // 检查是否已触发过 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", "Custom event was triggered");
      }
      // 使用 %.*s 格式记录 StringRef
      ESP_LOGD("main", "Last event: %.*s", (int) event_type.size(), event_type.c_str());
    }

参见

• API 参考：event.h