十三 Home Assistant 事件的监听

监听事件

你的集成可能需要在Home Assistant内部发生特定事件时采取行动。Home Assistant提供了事件助手来监听特定事件类型，并提供对事件总线的直接访问。这些助手经过高度优化，以尽量减少回调的数量。如果已经有针对你需要监听的特定事件的助手，那么使用助手比直接监听事件总线更可取。

可用的事件助手

事件助手位于homeassistant.helpers.event命名空间中。这些函数返回一个可调用对象，用于取消监听器。

以下函数也有同步版本，没有async_前缀。

示例：

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

跟踪实体状态变化

函数	用例
async_track_state_change	跟踪特定状态变化
async_track_state_change_event	按实体ID跟踪特定状态变化事件
async_track_state_added_domain	跟踪实体添加到域时的状态变化事件
async_track_state_removed_domain	跟踪实体从域中移除时的状态变化事件
async_track_state_change_filtered	使用可更新的TrackStates过滤器跟踪状态变化
async_track_same_state	跟踪实体状态一段时间并运行一个操作

跟踪模板变化

函数	用例
async_track_template	添加一个监听器，当模板求值为true时触发
async_track_template_result	添加一个监听器，当模板结果发生变化时触发

跟踪实体注册表变化

函数	用例
async_track_entity_registry_updated_event	按实体ID跟踪特定实体注册表更新事件

跟踪时间变化

函数	用例
async_track_point_in_time	添加一个监听器，在特定时间点之后触发一次
async_track_point_in_utc_time	添加一个监听器，在特定UTC时间点之后触发一次
async_call_later	添加一个带有延迟的监听器
async_track_time_interval	添加一个监听器，每隔一段时间间隔重复触发
async_track_utc_time_change	添加一个监听器，如果时间匹配模式则触发
async_track_time_change	添加一个监听器，如果本地时间匹配模式则触发

跟踪太阳

函数	用例
async_track_sunrise	添加一个监听器，每天在日出后指定偏移量时触发
async_track_sunset	添加一个监听器，每天在日落后指定偏移量时触发

直接监听事件总线

有两个函数可用于创建监听器。两个函数都返回一个可调用对象，用于取消监听器。

• async_listen_once - 监听事件一次，之后不再触发。
• async_listen - 持续监听，直到取消。

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

异步上下文

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

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

同步上下文

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

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

常见事件

以下事件通常直接被监听。

事件名称	描述
EVENT_HOMEASSISTANT_START	完成设置并进入启动阶段
EVENT_HOMEASSISTANT_STARTED	完成启动阶段，所有集成都有机会加载；主要由语音助手和将状态导出到外部服务的集成使用
EVENT_HOMEASSISTANT_STOP	进入停止阶段

其他事件

除非集成是核心的一部分，否则这些事件很少直接被监听。通常有一个助手可以处理这些事件，在这种情况下，不应直接监听它们。

事件名称	描述	首选助手
EVENT_HOMEASSISTANT_FINAL_WRITE	最后一次将数据写入磁盘的机会	无
EVENT_HOMEASSISTANT_CLOSE	拆卸	无
EVENT_COMPONENT_LOADED	一个集成已完成加载	homeassistant.helpers.start.async_at_start
EVENT_SERVICE_REGISTERED	一个新服务已注册	无
EVENT_SERVICE_REMOVED	一个服务已被移除	无
EVENT_CALL_SERVICE	一个服务已被调用	无
EVENT_STATE_CHANGED	一个实体的状态已改变	跟踪实体状态变化相关助手
EVENT_THEMES_UPDATED	主题已更新	无
EVENT_CORE_CONFIG_UPDATE	核心配置已更新	无
EVENT_ENTITY_REGISTRY_UPDATED	实体注册表已更新	跟踪实体注册表变化相关助手