监听事件#

你的 integration 可能需要对 Home Assistant 内部发生的特定事件采取行动。Home Assistant 提供了 event helpers 来监听特定的 event 类型，并且可以直接访问 event bus。这些 helpers 经过高度优化，以尽量减少回调数量。如果你需要监听的事件已经有对应的 helper，那么优先使用 helper 而不是直接监听 event bus。

#可用的 event helpers

Event helpers 位于 homeassistant.helpers.event 命名空间中。这些函数返回一个用于取消 listener 的 callable。

这些函数中许多也有不带 async_ 前缀的同步版本。

#示例

unsub = async_track_state_change_event(hass, entity_ids, state_automation_listener)
unsub()

#跟踪 entity state 变更

#跟踪 template 变更

#跟踪 entity registry 变更

#跟踪时间变更

#跟踪太阳

#直接监听 event bus

有两个函数可用于创建 listeners。这两个函数都返回一个取消 listener 的 callable。

• async_listen_once — 监听一次该 event，之后不再触发
• async_listen — 持续监听直到被取消

async_listen 很少被使用，因为 EVENT_HOMEASSISTANT_START、EVENT_HOMEASSISTANT_STARTED 和 EVENT_HOMEASSISTANT_STOP 每次运行只触发一次。

#Async context

cancel = hass.bus.async_listen_once(EVENT_HOMEASSISTANT_STOP, disconnect_service)
cancel()

cancel = hass.bus.async_listen(EVENT_STATE_CHANGED, forward_event)
cancel()

#Sync context

cancel = hass.bus.listen_once(EVENT_HOMEASSISTANT_STOP, disconnect_service)
cancel()

cancel = hass.bus.listen(EVENT_STATE_CHANGED, forward_event)
cancel()

#常见 events

以下 events 通常被直接监听。

#其他 events

这些 events 很少被直接监听，除非该 integration 属于 core。通常会有消耗这些 events 的 helper 可用，此时不应直接监听。