热水器组件

water_heater 组件是 ESPHome 中热水器（锅炉）的通用表示。热水器处理目标温度设定点和操作模式（如 Eco、Electric 或 Performance）。

NOTE

热水器集成适用于 Home Assistant 2026.2 及更高版本。

基础热水器配置

所有热水器配置模式都继承自此模式——您可以为热水器设置这些键。

water_heater:
  - platform: ...

配置变量：

id (可选, string): 手动指定用于代码生成的 ID。至少必须指定 id 和 name 中的一个。
name (可选, string): 热水器的名称。至少必须指定 id 和 name 中的一个。

NOTE

如果您为设备设置了 friendly_name，并希望热水器使用该名称，可以将 name: None。

icon (可选, icon): 手动设置在前端中为热水器使用的图标。

高级选项：

visual (可选): 前端表示的配置。
- min_temperature (可选, float): 覆盖前端中显示的最小温度。
- max_temperature (可选, float): 覆盖前端中显示的最大温度。
- target_temperature_step (可选, float): 覆盖前端中显示的温度步进。
supported_modes (可选, list): 将暴露给前端的静态操作模式列表（例如 Home Assistant）。未指定时，平台支持的所有模式都将暴露。

注意此选项因平台而异。并非所有热水器平台都允许配置支持的模式。
internal (可选, boolean): 将此组件标记为内部组件。内部组件将不会暴露给前端（如 Home Assistant）。仅指定不带 name 的 id 将隐式地将此设置为 true。
disabled_by_default (可选, boolean): 如果为 true，则此实体不应被添加到任何客户端的前端中，（通常是 Home Assistant），除非用户手动启用它（通过 Home Assistant UI）。默认为 false。
entity_category (可选, string): 实体的类别。请参阅 https://developers.home-assistant.io/docs/core/entity/#generic-properties 了解可用选项列表。设置为 "" 以移除默认实体类别。
如果启用了 Webserver 并选择了版本 3，则还包括 Webserver 组件的所有其他选项。请参阅 Webserver Version 3。

MQTT 选项：

mode_command_topic (可选, string): 用于接收模式命令的主题。
mode_state_topic (可选, string): 用于发布模式状态变更的主题。
target_temperature_command_topic (可选, string): 用于接收目标温度命令的主题。
target_temperature_state_topic (可选, string): 用于发布目标温度状态变更的主题。
还包括 MQTT 组件的所有其他选项。

`water_heater.control` 操作

此 action 允许您设置热水器的操作模式和/或目标温度。

on_...:
  then:
    - water_heater.control:
        id: boiler_1
        mode: ECO
        target_temperature: 55.0

配置变量：

id (必填, ID): 要控制的热水器。
mode (可选, string): 要设置的操作模式。请参阅 Modes 了解可用选项。
target_temperature (可选, float): 要设置的目标温度（例如 60.0）。

NOTE

此操作也可以表示为 lambdas：

auto call = id(boiler_1).make_call();
call.set_mode("PERFORMANCE");
call.set_target_temperature(65.0);
call.perform();

热水器模式

以下为热水器可用的模式。注意并非所有平台都支持所有模式。

OFF
ECO
ELECTRIC
PERFORMANCE
HIGH_DEMAND
HEAT_PUMP
GAS

Lambdas

在 lambdas 中，您可以访问热水器的当前状态。

current_temperature : 检索当前测量的水温（float）。

    if (id(my_boiler).current_temperature < 40.0) {
      // 水是冷的
    }

target_temperature : 检索目标设定点温度（float）。
mode : 检索当前操作模式。

    if (id(my_boiler).mode == water_heater::WATER_HEATER_MODE_ECO) {
      // 锅炉处于 ECO 模式
    } else if (id(my_boiler).mode == water_heater::WATER_HEATER_MODE_PERFORMANCE) {
      // 锅炉处于 PERFORMANCE 模式
    }

可用的 C++ 模式枚举：

water_heater::WATER_HEATER_MODE_OFF
water_heater::WATER_HEATER_MODE_ECO
water_heater::WATER_HEATER_MODE_ELECTRIC
water_heater::WATER_HEATER_MODE_PERFORMANCE
water_heater::WATER_HEATER_MODE_HIGH_DEMAND
water_heater::WATER_HEATER_MODE_HEAT_PUMP
water_heater::WATER_HEATER_MODE_GAS

热水器组件

基础热水器配置

water_heater.control 操作

热水器模式

Lambdas

另请参阅

`water_heater.control` 操作