跳转到内容
ESPHome - 让智能家居更简单2026.7.0

输出组件

output 领域的每个平台都会向 ESPHome 暴露一些输出。它们被分为两类：binary 输出 （只能为 ON/OFF）和 float 输出（如 PWM，可以输出 0 到 1 之间的任何有理数）。

基础输出配置

Section titled “基础输出配置”

每个输出平台都扩展了此配置模式。

# Example configuration entry
output:
  - platform: ...
    id: my_output_id
    power_supply: power_supply_id
    inverted: false
    min_power: 0.01
    max_power: 0.75

配置变量：

  • id (必需, ID): 用于此输出组件的 id。

  • power_supply (可选, ID): 要连接到 此输出的 电源。当输出启用时，电源将 自动随之开启。

  • inverted (可选, boolean): 是否应将输出视为反相。默认为 false。

仅适用于浮点输出：

  • min_power (可选, float): 设置此输出平台的最小输出值。 必须位于 0 到 max_power 之间。默认为 0。如果 zero_means_zero 为 false，这将在实体关闭时的输出值。

  • max_power (可选, float): 设置此输出平台的最大输出值。 必须位于 min_power 到 1 之间。默认为 1。

  • zero_means_zero (可选, boolean): 设置输出使用实际 0 而不是 min_power。 默认为 false。

NOTE

min_power 和 max_power 值会自动进行钳位，以确保 0.0 ≤ min_power ≤ max_power ≤ 1.0。 这可以防止无效配置并确保输出行为稳定。

output.turn_on 操作

Section titled “output.turn_on 操作”

此操作在执行时开启给定 ID 的输出。

on_...:
  then:
    - output.turn_on: light_1

NOTE

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

id(light_1).turn_on();

output.turn_off 操作

Section titled “output.turn_off 操作”

此操作在执行时关闭给定 ID 的输出。

on_...:
  then:
    - output.turn_off: light_1

NOTE

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

id(light_1).turn_off();

output.set_level 操作

Section titled “output.set_level 操作”

此操作在执行时将浮点输出设置为给定级别。

NOTE

此操作仅适用于浮点输出，如 Ac Dimmer、 Esp8266 Pwm、Ledc、 Sigma Delta Output、Slow Pwm。

on_...:
  then:
    - output.set_level:
        id: light_1
        level: 50%

NOTE

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

// range is 0.0 (off) to 1.0 (on)
id(light_1).set_level(0.5);

output.set_min_power 操作

Section titled “output.set_min_power 操作”

此操作为指定的浮点输出平台设置最小输出功率级别。 它允许你在运行时动态调整 min_power 配置变量。

NOTE

此操作仅适用于浮点输出，如 Ac Dimmer、 Esp8266 Pwm、Ledc、 Sigma Delta Output、Slow Pwm。

on_...:
  then:
    - output.set_min_power:
        id: light_1
        min_power: 20%

NOTE

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

// range is 0.0 (off) to 1.0 (on)
id(light_1).set_min_power(0.2);

从 lambda 中调用 set_min_power() 需要运行时功率缩放被 编译进去。只有当至少一个输出条目设置了 min_power、max_power 或 zero_means_zero，或者注册了任何 output.set_min_power / output.set_max_power 操作时，它才会被编译进去。如果你的 配置两者都未使用，请为某个输出添加 min_power: 0% 以启用 —— 否则 编译将因指向该 lambda 的 static_assert 而失败。

output.set_max_power 操作

Section titled “output.set_max_power 操作”

此操作为指定的浮点输出平台设置最大输出功率级别。 它允许你在运行时动态调整 max_power 配置变量。

NOTE

此操作仅适用于浮点输出，如 Ac Dimmer、 Esp8266 Pwm、Ledc、 Sigma Delta Output、Slow Pwm。

on_...:
  then:
    - output.set_max_power:
        id: light_1
        max_power: 80%

NOTE

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

// range is 0.0 (off) to 1.0 (on)
id(light_1).set_max_power(0.8);

从 lambda 中调用 set_max_power() 需要运行时功率缩放被 编译进去（参见上面 output.set_min_power 下的说明）。为某个 输出条目添加 max_power: 100% 就足以启用。

参见

Section titled “参见”