热水器组件

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

NOTE

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

基本热水器配置

所有热水器配置架构继承自此架构 - 您可以为热水器设置这些键。

water_heater:
  - platform: ...

配置变量：

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

NOTE

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

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

高级选项：

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

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

MQTT 选项：

mode_command_topic (可选, 字符串)：接收模式命令的主题。
mode_state_topic (可选, 字符串)：发布模式状态更改的主题。
target_temperature_command_topic (可选, 字符串)：接收目标温度命令的主题。
target_temperature_state_topic (可选, 字符串)：发布目标温度状态更改的主题。
来自 MQTT 组件的所有其他选项。

`water_heater.control` 动作

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

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

配置变量：

id (*必需, ID)：要控制的热水器。
mode (可选, 字符串)：要设置的操作模式。有关可用选项，请参阅模式。
target_temperature (可选, 浮点数)：要设置的目标温度（例如 60.0）。

NOTE

此动作也可以在 lambda 中表达：

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

Lambda

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

current_temperature：获取当前测量的水温（浮点数）。

    if (id(my_boiler).current_temperature < 40.0) {
      // 水温低
    }

target_temperature：获取目标设定点温度（浮点数）。
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 动作

热水器模式

Lambda

另见

`water_heater.control` 动作