Light 组件

在 ESPHome 中，light 组件允许你创建可用于 Home Assistant 前端的灯光，并具有多种功能，如颜色、过渡以及效果。

此组件可以在重启/重置时恢复其状态（如果配置为这样做）。

基础 Light 配置

所有 light 配置模式都继承这些选项。

light:
  - platform: ...

配置变量

platform（必选，platform）：一个灯光平台。
id（可选，string）：手动指定用于代码生成的 ID。必须指定 id 和 name 中的至少一个。
name（可选，string）：灯光的名称。必须指定 id 和 name 中的至少一个。

NOTE

如果你的设备设置了 friendly_name，并且你希望灯光使用该名称，你可以设置 name: None。

icon（可选，icon）：手动设置在前端中用于灯光的图标。
effects（可选，list）：一组用于此灯光的灯光效果。
gamma_correct（可选，float）：对灯光通道应用伽马校正因子。默认为 2.8。
default_transition_length（可选，Time）：当 light 调用中未设置过渡时长时要使用的默认过渡时长。默认为 1s。
flash_transition_length（可选，Time）：调用 flash 时要使用的过渡时长。默认为 0s。
initial_state（可选）：启动时灯光应设置的初始状态。此状态将在状态未基于 restore_mode（下文）恢复时应用。
- state（可选，boolean，templatable）：灯光的 ON/OFF 状态。
- 来自 light 状态的所有其他选项。
restore_mode（可选）：控制灯光在启动时尝试恢复状态的方式。
- RESTORE_DEFAULT_OFF - 尝试恢复状态，如果无法恢复则默认为 OFF。
- RESTORE_DEFAULT_ON - 尝试恢复状态，默认为 ON。
- RESTORE_INVERTED_DEFAULT_OFF - 尝试恢复反转于先前状态的状态，默认为 OFF。
- RESTORE_INVERTED_DEFAULT_ON - 尝试恢复反转于先前状态的状态，默认为 ON。
- RESTORE_AND_OFF - 尝试恢复状态，但将灯光初始化为 OFF。
- RESTORE_AND_ON - 尝试恢复状态，但将灯光初始化为 ON。
- ALWAYS_OFF（默认）- 启动时始终将灯光初始化为 OFF。
- ALWAYS_ON - 启动时始终将灯光初始化为 ON。
on_turn_on（可选，Action）：灯光打开时要执行的自动化。参见 light.on_turn_on / light.on_turn_off 触发器。
on_turn_off（可选，Action）：灯光关闭时要执行的自动化。参见 light.on_turn_on / light.on_turn_off 触发器。
on_state（可选，Action）：灯光的设置状态更改时要执行的自动化。参见 light.on_state 触发器。

地址化灯光的额外配置变量：

color_correct（可选，float 列表）：对每个颜色通道应用颜色校正。它定义了每个通道的最大亮度。例如 [100%, 50%, 100%] 将设置绿色通道最多处于 50% 亮度。
power_supply（可选，ID）：要连接到此灯光的 Power Supply。当灯光打开时，电源也会自动开启。

高级选项：

internal（可选，boolean）：将该组件标记为内部组件。内部组件不会暴露给前端（如 Home Assistant）。只指定 id 而不指定 name 将隐式将其设为 true。
disabled_by_default（可选，boolean）：如果为 true，则此实体不应被添加到任何客户端的前端中，（通常为 Home Assistant），除非用户手动启用它（通过 Home Assistant UI）。默认为 false。
entity_category（可选，string）：实体的类别。有关可用选项列表，请参见此列表。设为 "" 以移除默认的实体类别。
如果启用了 MQTT，还包含 MQTT Component 的所有其他选项。
如果启用了 Webserver 并选择了版本 3，还包含 Web Server 的所有其他选项。

Light 状态

一些动作/配置会引用 light 状态。light 状态 可以由以下任何配置变量组成：

color_mode（可选，templatable）：对于支持多种颜色模式的灯光，将激活的颜色模式。颜色模式决定了灯光的哪些输出处于活动状态，以及可以使用哪些参数。例如，这可用于在彩色光和白光之间切换。必须是一种灯光支持的颜色模式。有效的颜色模式有：
- ON_OFF : 仅开/关控制。
- BRIGHTNESS : 仅亮度控制。接受 brightness 参数。
- WHITE : 仅单一白色通道。接受 brightness 和 white 参数。
- COLOR_TEMPERATURE : 通过色温控制的白色通道。接受 brightness 和 color_temperature
  
  参数。
- COLD_WARM_WHITE : 冷白和暖白通道。接受 brightness、color_temperature、cold_white 和
  
  warm_white 参数。
- RGB : RGB 颜色通道。接受 brightness、color_brightness、red、green 和 blue 参数。
- RGB_WHITE : RGB 颜色通道和单独的白色通道。接受 RGB 和 WHITE 颜色模式的参数。
- RGB_COLOR_TEMPERATURE : RGB 颜色通道和单独的色温控制白色通道。接受 RGB 和 COLOR_TEMPERATURE 颜色模式的参数。
- RGB_COLD_WARM_WHITE : RGB 颜色通道和两个单独的冷白和暖白通道。接受 RGB 和 COLD_WARM_WHITE 颜色模式的参数。
brightness（可选，percentage，templatable）：灯光的主要亮度；适用于灯光的所有通道（颜色和白色）。
color_brightness（可选，percentage，templatable）：彩色灯光的亮度。可用于为 RGBW 灯光单独控制彩色灯光和白光的亮度。
red（可选，percentage，templatable）：灯光的红色通道。
green（可选，percentage，templatable）：灯光的绿色通道。
blue（可选，percentage，templatable）：灯光的蓝色通道。
white（可选，percentage，templatable）：白色通道的亮度。
color_temperature（可选，float，templatable）：白色通道的色温（以 mireds 或开尔文为单位）。
cold_white（可选，percentage，templatable）：冷白通道的亮度。不能与 color_temperature 同时使用。
warm_white（可选，percentage，templatable）：暖白通道的亮度。不能与 color_temperature 同时使用。

所有百分比选项接受范围在 0% 到 100% 或 0.0 到 1.0 之间的值，它们默认为不更改当前值（这可能是灯光上次关闭前的值）。要重置值，请显式将其设为零。

Light 自动化

`light.toggle` 动作

执行此动作时，将以给定 ID 切换灯光。

on_...:
  then:
    - light.toggle:
        id: light_1
    # 简写：
    - light.toggle: light_1

配置变量：

id（必选，ID）：灯光的 ID。
transition_length（可选，Time，templatable）：如果灯光支持的话，过渡的时长。

NOTE

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

auto call = id(light_1).toggle();
// 执行动作：
call.perform();

`light.turn_on` 动作

执行此动作时，将以给定 ID 打开灯光。

on_...:
  then:
    - light.turn_on:
        id: light_1
        brightness: 100%
        red: 100%
        green: 100%
        blue: 1.0
    # 模板化
    - light.turn_on:
        id: light_1
        brightness: !lambda |-
          // 输出值必须在 0 - 1.0 范围内
          return id(some_sensor).state / 100.0;
    # 简写
    - light.turn_on: light_1

配置变量：

id（必选，ID）：灯光的 ID。
transition_length（可选，Time，templatable）：如果灯光支持的话，过渡的时长。
flash_length（可选，Time，templatable）：如果设置，将闪烁指定颜色此时间段，然后返回到先前状态。
effect（可选，string，templatable）：如果设置，将尝试启动具有给定名称的效果。
来自 light 状态的所有其他选项。

NOTE

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

auto call = id(light_1).turn_on();
// 设置参数（可选）
call.set_transition_length(1000); // 单位：毫秒
call.set_brightness(1.0); // 1.0 表示满亮度
call.set_color_mode(ColorMode::RGB_COLD_WARM_WHITE);
call.set_rgb(0.5, 0.25, 1.0); // 颜色按 RGB 顺序，此示例为紫色
call.set_cold_white(0.5);
call.set_warm_white(0.75);
call.set_effect("The Effect");
// 执行动作：
call.perform();

使用 auto call、call.set_brightness 和 call.perform 的简短短例。

id(light_1).turn_on().set_brightness(1.0).perform();

NOTE

red、green 和 blue 值仅控制灯光的颜色，不控制其亮度！如果你将所有 RGB 通道设为 50%，它将被解释为 100% 开启。只使用 brightness 或 color_brightness 来控制灯光的亮度。

NOTE

主亮度（brightness ）和颜色通道与白色通道的独立亮度控制（color_brightness、white、cold_white 和 warm_white ）会相乘。因此，这将导致颜色为 40% 亮度、白色为 60% 亮度：

- light.turn_on:
    id: light_1
    brightness: 80%
    color_brightness: 50%
    white: 75%

`light.turn_off` 动作

执行此动作时，将以给定 ID 关闭灯光。

on_...:
  then:
    - light.turn_off:
        id: light_1
    # 简写
    - light.turn_off: light_1

配置变量：

id（必选，ID）：灯光的 ID。
transition_length（可选，Time，templatable）：如果灯光支持的话，过渡的时长。

NOTE

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

auto call = id(light_1).turn_off();
// 设置参数（可选）
call.set_transition_length(1000); // 单位：毫秒
// 执行动作：
call.perform();

`light.control` 动作

此 Action 是用于更改灯光状态的通用调用——它本质上只是 turn_on 和 turn_off 调用的组合。

on_...:
  then:
    - light.control:
        id: light_1
        state: on

配置变量：

id（必选，ID）：灯光的 ID。
state（可选，templatable，boolean）：更改灯光的 ON/OFF 状态。
来自 light 状态的所有其他选项。

`light.dim_relative` 动作

此 Action 允许你将支持亮度的灯光按相对量进行调光。

on_...:
  then:
    # 将亮度提高 5%
    - light.dim_relative:
        id: light_1
        relative_brightness: 5%

配置变量：

id（必选，ID）：灯光的 ID。
relative_brightness（必选，templatable，percentage）：要调光的相对亮度。
transition_length（可选，Time，templatable）：过渡的时长。
brightness_limits（可选）：亮度范围内的限制。
- min_brightness（可选，percentage）：将灯光调暗到的最小亮度。默认为 0%。
- max_brightness（可选，percentage）：将灯光调暗到的最大亮度。默认为 100%。
- limit_mode（可选）：当当前亮度超出限制范围时该怎么做。默认为
  
  CLAMP。有效的限制模式有：
  - CLAMP : 将亮度限制在限制范围内。
  - DO_NOTHING : 如果亮度超出限制范围则不调光。

NOTE

示例：通过按钮按下调暗灯光

binary_sensor:
  - platform: gpio
    # ...
    id: my_binary_sensor
    on_press:
      - while:
          condition:
            binary_sensor.is_on: my_binary_sensor
          then:
            - light.dim_relative:
                id: light_1
                relative_brightness: 5%
                transition_length: 0.1s
                brightness_limits:
                    max_brightness: 90%
            - delay: 0.1s

`light.effect.next` / `light.effect.previous` 动作

这些 Action 循环切换为灯光配置的效果。light.effect.next 前进到下一个效果；light.effect.previous 回到上一个效果。循环在两端环绕。

on_...:
  then:
    - light.effect.next:
        id: light_1
    # 简写
    - light.effect.next: light_1
    - light.effect.previous:
        id: light_1
        include_none: true

配置变量：

id（必选，ID）：灯光的 ID。
include_none（可选，boolean）：如果为 true，“None”（无效果）将作为循环中的一个步骤，因此灯光在环绕时将经过无效果状态。如果为 false，则仅循环切换配置的效果，跳过”None”。默认为 false。

NOTE

如果灯光没有活动效果且 include_none 为 false，第一次调用将跳转到第一个配置的效果。所引用的灯光必须至少配置一个效果；这会在配置验证时检查。

NOTE

如果灯光尚未打开，此动作会将其打开，以便所选效果立即开始。要仅在灯光开启时循环切换效果，请使用 light.is_on 条件对动作进行门控。

`light.addressable_set` 动作

此 Action 允许你手动将可寻址灯光上的一组 LED 设为特定颜色。

on_...:
  - light.addressable_set:
      id: my_light
      range_from: 0
      range_to: 50
      red: 100%
      green: 0%
      blue: 0%

配置变量：

id（必选，ID）：要控制的可寻址灯光的 ID。
range_from（可选，templatable，int）：要控制的 LED 范围的起始位置（含），使用基于零的索引。默认为 0（灯带的开头）。
range_to（可选，templatable，int）：要控制的 LED 范围的结束位置（含），使用基于零的索引。默认为灯带的末尾（num_leds - 1）。
color_brightness（可选，templatable，percentage）：要设置颜色通道的亮度。
red（可选，templatable，percentage）：要设置红色通道的值。
green（可选，templatable，percentage）：要设置绿色通道的值。
blue（可选，templatable，percentage）：要设置蓝色通道的值。
white（可选，templatable，percentage）：要设置白色通道的亮度。

Light 条件

`light.is_on` / `light.is_off` 条件

此 Condition 检查给定灯光是否处于 ON 或 OFF。OFF 表示灯光完全关闭，ON 表示灯光至少发出一点光。

# 在某个触发器中：
on_...:
  if:
    condition:
      # is_off 使用相同语法
      light.is_on: my_light

Light 触发器

`light.on_turn_on` / `light.on_turn_off` 触发器

每当灯光打开或关闭时都会激活此触发器。它与上述 light.is_on 和 light.is_off 条件的行为一致。

light:
  - platform: binary # 或任何其他平台
    # ...
    on_turn_on:
    - logger.log: "Light Turned On!"
    on_turn_off:
    - logger.log: "Light Turned Off!"

`light.on_state` 触发器

每当设置的灯光状态更改时都会激活此触发器。它不是基于当前状态触发的，而是在设置状态上触发，设置状态可能由于过渡而不同于当前状态。例如， light.on_state 触发器可用于在灯光设为关闭时立即执行动作；而 light.on_turn_off 直到灯光实际达到关闭状态才会触发。

light:
  - platform: binary # 或任何其他平台
    # ...
    on_state:
    - logger.log: "Light State Changed!"

Light 效果

ESPHome 有几个内置/预定义的灯光效果，你可以用于灯光。效果参数的默认值本身工作得很好，但 ESPHome 也允许你手动更改这些参数。

你在 ESPHome 中定义的每个效果都会作为灯光在 Home Assistant 中效果下拉菜单中的条目出现。如果你希望拥有同一效果的几个变体，可以创建多个条目，每个条目具有唯一名称：

light:
  - platform: ...
    # ...
    effects:
      # 使用默认参数：
      - random:
      # 自定义参数
      - random:
          name: "My Slow Random Effect"
          transition_length: 30s
          update_interval: 30s
      - random:
          name: "My Fast Random Effect"
          transition_length: 4s
          update_interval: 5s

NOTE

设置灯光效果后，可以通过在通过 Home Assistant 调用或在设备上直接调用时将 effect 设为 none 来将正在使用的效果重置回静态灯光。

基础动画

这些效果适用于任何灯光平台。

效果	描述	参数
Pulse	平滑亮度脉冲	`name`、`transition_length`、`update_interval`、`min_brightness`、`max_brightness`
Random	固定间隔的随机颜色	`name`、`transition_length`、`update_interval`
Strobe	循环一组指定时长的颜色	`name`、`colors`
Flicker	类似蜡烛的亮度变化	`name`、`alpha`、`intensity`
Lambda	每次更新时运行自定义 C++	`name`、`update_interval`、`lambda`

灯带动画

这些效果需要可寻址灯光（LED 灯带）。

效果	描述	参数
Addressable Rainbow	色相沿灯带长度扫过	`name`、`speed`、`width`
Addressable Color Wipe	新颜色从灯带开头移入	`name`、`colors`、`add_led_interval`、`reverse`
Addressable Scan	单个点在灯带上前后滑动	`name`、`move_interval`、`scan_width`
Addressable Twinkle	随机像素变亮和变暗	`name`、`twinkle_probability`、`progress_interval`
Addressable Random Twinkle	闪烁，但每个像素获得随机颜色	`name`、`twinkle_probability`、`progress_interval`
Addressable Fireworks	火花从随机像素爆发	`name`、`update_interval`、`spark_probability`、`use_random_color`、`fade_out_rate`
Addressable Flicker	每像素蜡烛闪烁	`name`、`update_interval`、`intensity`
Addressable Lambda	每 LED 运行自定义 C++	`name`、`update_interval`、`lambda`

外部控制

这些效果从外部源接收帧，而不是在本地生成动画。

效果	描述	参数
Automation	在循环中运行 ESPHome 自动化动作	`name`、`sequence`
E1.31	通过网络接收 sACN / E1.31 帧	`universe`、`channels`
Adalight	通过 UART 接收 Adalight 协议	`uart_id`
WLED	接收 WLED UDP 同步协议	`port`、`blank_on_start`、`sync_group_mask`

脉冲效果

此效果使灯光脉冲。周期可以通过 update_interval 定义，过渡时长通过 transition_length 定义。transition_length 应设置为小于 update_interval，将 transition_length 设为 1s 且 update_interval 设为 2s 将产生从 0% 到 100% 持续 1 秒的过渡、1 秒满光、从 100% 到 0% 持续 1 秒的过渡以及 1 秒关闭。

light:
  - platform: ...
    # ...
    effects:
      - pulse:
      - pulse:
          name: "Fast Pulse"
          transition_length: 0.5s
          update_interval: 0.5s
          min_brightness: 0%
          max_brightness: 100%
      - pulse:
          name: "Slow Pulse"
          transition_length: 500ms
          update_interval: 2s
      - pulse:
          name: "Asymmetrical Pulse"
          transition_length:
            on_length: 1s
            off_length: 500ms
          update_interval: 1.5s

配置变量：

name（可选，string）：效果的名称。默认为 Pulse。
transition_length（可选，Time）：每次过渡的持续时间。默认为 1s。可以是单一时长，也可以使用以下嵌套选项将其拆分为开和关。
- on_length（可选，Time）：灯光打开时过渡的持续时间。
- off_length（可选，Time）：灯光关闭时过渡的持续时间。
update_interval（可选，Time）：启动新过渡的间隔。默认为 1s。
min_brightness（可选，percentage）：最小亮度值。默认为 0%
max_brightness（可选，percentage）：最大亮度值。默认为 100%

随机效果

此效果每经过 update_interval 时间，就向随机选择的颜色和/或亮度（对于单色）进行过渡（时长为 transition_length ）。

light:
  - platform: ...
    # ...
    effects:
      - random:
      - random:
          name: Random Effect With Custom Values
          transition_length: 5s
          update_interval: 7s

配置变量：

name（可选，string）：效果的名称。默认为 Random。
transition_length（可选，Time）：每次开始过渡的持续时间。默认为 5s。
update_interval（可选，Time）：选择新颜色并过渡到该颜色的间隔。

频闪效果

此效果以特定时长循环一组颜色。

light:
  - platform: ...
    # ...
    effects:
      - strobe:
      - strobe:
          name: Strobe Effect With Custom Values
          colors:
            - state: true
              brightness: 100%
              red: 100%
              green: 90%
              blue: 0%
              duration: 500ms
            - state: false
              duration: 250ms
            - state: true
              brightness: 100%
              red: 0%
              green: 100%
              blue: 0%
              duration: 500ms

配置变量：

name（可选，string）：效果的名称。默认为 Strobe。
colors（可选，list）：要循环的颜色列表。默认为在 ON 和 OFF 之间快速循环。
- state（可选，boolean）：要显示的开关状态。默认为 true。
- color_mode（可选，string）：灯光的颜色模式。默认为当前颜色模式。
- brightness（可选，percentage）：灯光的亮度。默认为 100%。
- color_brightness（可选，percentage）：RGB 灯光的亮度（如适用）。默认为 100%。
- red（可选，percentage）：灯光的红色通道（如适用）。默认为 100%。
- green（可选，percentage）：灯光的绿色通道（如适用）。默认为 100%。
- blue（可选，percentage）：灯光的蓝色通道（如适用）。默认为 100%。
- white（可选，percentage）：灯光的白色通道（如适用）。默认为 100%。
- color_temperature（可选，float）：灯光的色温（以 mireds 或开尔文为单位）（如适用）。
- cold_white（可选，percentage）：灯光的冷白通道（如适用）。默认为 100%。
- warm_white（可选，percentage）：灯光的暖白通道（如适用）。默认为 100%。
- duration（必选，Time）：此颜色应保持活动的持续时间。
- transition_length（可选，Time）：每次过渡的持续时间。默认为 0s。

有关各种颜色字段的更多信息，请参见 light 状态。

闪烁效果

此效果对亮度和所有颜色通道应用随机变化，这些变化在灯光的活动颜色附近“浮动”。默认值模拟温和的蜡烛闪烁，但通过不同的设置可以产生微妙的颜色变化或混乱的火花噪声。

light:
  - platform: ...
    # ...
    effects:
      - flicker:
      - flicker:
          name: Flicker Effect With Custom Values
          alpha: 95%
          intensity: 1.5%

配置变量：

name（可选，string）：效果的名称。默认为 Flicker。
alpha（可选，percentage）：一个平滑因子，控制闪烁的“记忆”程度。高值使闪烁的下一步与其上一步非常相似，从而平滑变化。低值混合更多新值，导致快速变化。默认为 95%。
intensity（可选，percentage）：每步应用的随机变化幅度。由于变化跨越颜色通道应用，较高值会产生更明显的偏移。默认为 1.5%。

Lambda 效果

此效果允许你使用 lambda 编写完全自定义的灯光效果。

lambda 中的可用变量：

it - API 参考：LightState 实例，对应运行此效果的灯光，允许你直接引用灯光而不需要它的 id（更多信息请参见 API 引用）。
initial_run - 一个布尔值，在 lambda 首次执行时为 true。在重启效果时重置静态变量很有用。

light:
  - platform: ...
    # ...
    effects:
      - lambda:
          name: My Custom Effect
          update_interval: 1s
          lambda: |-
            static int state = 0;
            auto call = it.turn_on();
            // Transition of 1000ms = 1s
            call.set_transition_length(1000);
            if (state == 0) {
              call.set_rgb(1.0, 1.0, 1.0);
            } else if (state == 1) {
              call.set_rgb(1.0, 0.0, 1.0);
            } else if (state == 2) {
              call.set_rgb(0.0, 0.0, 1.0);
            } else {
              call.set_rgb(1.0, 0.0, 0.0);
            }
            call.perform();
            state += 1;
            if (state == 4)
              state = 0;

配置变量：

name（必选，string）：自定义效果的名称。
update_interval（可选，Time）：lambda 代码执行间隔。值为 0ms 表示 lambda 始终执行，没有冷却。默认为 0ms。
lambda（必选，lambda）：要执行的代码。static 变量尤其有用。

访问效果名称

你可以使用 get_name() 方法访问灯光效果的名称，它返回一个 StringRef：

// 获取灯光的所有效果
auto &effects = id(my_light).get_effects();
for (auto *effect : effects) {
  StringRef name = effect->get_name();
  // 与字符串字面量比较
  if (name == "My Custom Effect") {
    ESP_LOGI("light", "Found my effect!");
  }
  // 使用显式大小的安全日志记录
  ESP_LOGI("light", "Effect: %.*s", (int) name.size(), name.c_str());
}

你也可以使用 get_effect_name() 从灯光状态获取当前活动效果的名称：

// 获取当前活动效果
StringRef current = id(my_light).get_effect_name();
if (current == "None") {
  ESP_LOGI("light", "No effect active");
} else {
  ESP_LOGI("light", "Active effect: %.*s", (int) current.size(), current.c_str());
}

可寻址彩虹效果

一个用于单独可寻址 LED 的灯光效果，使用 HSV 色轮在整个 LED 灯带上创建移动的彩虹。

light:
  - platform: ...
    # ...
    effects:
      - addressable_rainbow:
      - addressable_rainbow:
          name: Rainbow Effect With Custom Values
          speed: 10
          width: 50

配置变量：

name（可选，string）：效果的名称。默认为 Rainbow。
speed（可选，int）：效果的速度，无量纲。默认为 10。
width（可选，int）：全幅彩虹的“宽度”，无量纲。默认为 50。

可寻址颜色擦拭效果

一个用于单独可寻址 LED 的灯光效果，在灯带开头不断引入新颜色并在每个 add_led_interval 时向前移动。

light:
  - platform: ...
    # ...
    effects:
      - addressable_color_wipe:
      - addressable_color_wipe:
          name: Color Wipe Effect With Custom Values
          colors:
            - red: 100%
              green: 100%
              blue: 100%
              num_leds: 5
              gradient: true
            - red: 0%
              green: 0%
              blue: 0%
              num_leds: 1
          add_led_interval: 100ms
          reverse: false

配置变量：

name（可选，string）：效果的名称。默认为 Color Wipe。
colors（可选，list）：要在灯带开头移入的颜色。默认为移入随机颜色。
- red（可选，percentage）：红色颜色通道应开启的百分比。默认为 100%。
- green（可选，percentage）：绿色颜色通道应开启的百分比。默认为 100%。
- blue（可选，percentage）：蓝色颜色通道应开启的百分比。默认为 100%。
- random（可选，boolean）：如果设为 true，每次会用新的随机选择的颜色覆盖 RGB 颜色。默认为 false。
- num_leds（必选，positive int）：过渡到下一个颜色前此类型 LED 的数量。如果 gradient 为 true，这将是颜色过渡发生的 LED 数量。
- gradient（可选，boolean）：如果为 true，当前颜色将在 num_leds 上以渐变方式过渡到下一个颜色。默认为 false。
add_led_interval（可选，Time）：在灯带开头移入新 LED 的间隔。默认为 100ms。
reverse（可选，boolean）：是否反转颜色擦拭的方向。默认为 false。

可寻址扫描效果

创建一个单独的、快速移动的点在 LED 灯带上前后“滑动”。颜色由当前活动的灯光颜色选择。

light:
  - platform: ...
    # ...
    effects:
      - addressable_scan:
      - addressable_scan:
          name: Scan Effect With Custom Values
          move_interval: 100ms
          scan_width: 1

配置变量：

name（可选，string）：效果的名称。默认为 Scan。
move_interval（可选，Time）：将点/线向前移动一个 LED 的间隔。默认为 100ms。
scan_width（可选，int）：要使用的 LED 数量。默认为 1。

可寻址闪烁效果

随机选择 LED 并让其短暂变亮，模仿夜空中闪烁的星星。像素的颜色由当前灯光颜色决定。

light:
  - platform: ...
    # ...
    effects:
      - addressable_twinkle:
      - addressable_twinkle:
          name: Twinkle Effect With Custom Values
          twinkle_probability: 5%
          progress_interval: 4ms

配置变量：

name（可选，string）：效果的名称。默认为 Twinkle。
twinkle_probability（可选，percentage）：在任意时间步，随机选择的 LED 开始其闪烁动画的百分比。
progress_interval（可选，Time）：推进效果的间隔。它影响闪烁动画的持续时间。默认为 4ms。

可寻址随机闪烁效果

与 addressable_twinkle 类似但每个闪烁动画使用随机颜色的灯光效果。

light:
  - platform: ...
    # ...
    effects:
      - addressable_random_twinkle:
      - addressable_random_twinkle:
          name: Random Twinkle Effect With Custom Values
          twinkle_probability: 5%
          progress_interval: 32ms

配置变量：

name（可选，string）：效果的名称。默认为 Random Twinkle。
twinkle_probability（可选，percentage）：在任意时间步，随机选择的 LED 开始其闪烁动画的百分比。
progress_interval（可选，Time）：推进效果的间隔。它影响闪烁动画的持续时间。默认为 4ms。

可寻址烟花效果

一个用于单独可寻址 LED 灯带的灯光效果，在随机位置随机点燃烟花并让火花沿 LED 灯带扩散。

light:
  - platform: ...
    # ...
    effects:
      - addressable_fireworks:
      - addressable_fireworks:
          name: Fireworks Effect With Custom Values
          update_interval: 32ms
          spark_probability: 10%
          use_random_color: false
          fade_out_rate: 120

配置变量：

name（可选，string）：效果的名称。默认为 Fireworks。
update_interval（可选，Time）：推进效果的间隔。默认为 32ms。
spark_probability（可选，percentage）：在任意给定时间步，在随机选择的 LED 上启动新的烟花火花的概率。默认为 10%。
use_random_color（可选，boolean）：是否为新烟花火花使用随机颜色。默认为使用当前活动的灯光颜色。
fade_out_rate（可选，int）：LED 灯带淡出的速率，无量纲。需要仔细选择，以免淡出速率过低导致整个灯带永久发光，或烟花火花无法长时间传播。默认为 120。

可寻址闪烁效果

与 flicker 效果类似但用于单独可寻址 LED 灯带的效果。此效果使每个 LED 围绕当前活动的灯光颜色以各自随机的量闪烁。

light:
  - platform: ...
    # ...
    effects:
      - addressable_flicker:
      - addressable_flicker:
          name: Flicker Effect With Custom Values
          update_interval: 16ms
          intensity: 5%

配置变量：

name（可选，string）：效果的名称。默认为 Addressable Flicker。
update_interval（可选，Time）：更新随机偏移的时间间隔。默认为 16ms。
intensity（可选，percentage）：效果的强度，基本上随机值能将当前活动的灯光颜色偏移多少。默认为 5%。

可寻址 Lambda 效果

此效果允许你在自定义灯光效果中单独访问每个 LED。

lambda 中的可用变量：

it - API 参考：AddressableLight 实例（更多信息请参见 API 引用）。
current_color - API 参考：ESPColor 实例（更多信息请参见 API 引用）。
initial_run - 一个布尔值，在 lambda 首次执行时为 true。在重启效果时重置静态变量很有用。

NOTE

ESPColor 已迁移为 Color。更多信息请参见 API 参考：Color。

light:
- platform: ...
  effects:
    - addressable_lambda:
        name: "My Custom Effect"
        update_interval: 16ms
        lambda: |-
          // it.size() - LED 数量
          // it[num] - 访问索引为 num 的 LED。
          // 将索引 num 处的 LED 设为给定的 r、g、b 值
          // it[num] = Color(r, g, b);
          // 获取索引 num 处的颜色（Color 实例）
          // it[num].get();

          // 示例：简单颜色擦拭
          for (int i = it.size() - 1; i > 0; i--) {
            it[i] = it[i - 1].get();
          }
          it[0] = Color::random_color();

          // 附加：使用 .range() 和 .all() 在不编写循环的情况下设置多个 LED。
          it.range(0, 50) = Color::BLACK;
          it.all().fade_to_black(10);

light:
- platform: ...
  effects:
    - addressable_lambda:
        name: "My Custom Effect"
        update_interval: 16ms
        lambda: |-
          // 静态变量即使停止和重新启动效果也保持其值
          static uint16_t progress = 0;

          // 普通变量在每次执行后失去其值
          // 基本上在每个 update_interval 之后
          uint16_t changes = 0;

          // 要在停止和重新启动效果时重置静态变量
          // 可以使用 initial_run 变量
          if (initial_run) {
            progress = 0;
            it.all() = Color::BLACK;
            // 可以选择 return，以便在下一个 update_interval 之前什么也不发生
            return;
          }

此 API 的示例可以在源代码中找到（内置的可寻址灯光效果）。

自动化灯光效果

除了 lambda 和 addressable_lambda 灯光效果之外，还可以使用 ESPHome 的 Automation 系统和 automation 效果类型来创建效果。

在 sequence 块中给出的自动化将重复执行，直到效果被用户停止。

light:
- platform: ...
  id: my_light
  effects:
    - automation:
        name: Custom Automation Effect
        sequence:
          - light.addressable_set:
              id: my_light
              red: 100%
              green: 100%
              blue: 100%
          - delay: 100ms
          - light.addressable_set:
              id: my_light
              range_from: 0
              range_to: 20
              red: 100%
              green: 0%
              blue: 0%

配置变量：

name（可选，string）：效果的名称。
sequence（可选，Action）：要顺序执行直到效果停止的动作。

E1.31 效果

此效果通过基于 UDP 的 E1.31 协议来使可寻址灯光的控制成为可能。

例如，启用后，JINX 或 Hyperion.NG 可用于控制连接到 ESPHome 设备的 LED。

e131:
  method: multicast # 默认：将 E1.31 注册到多播组

light:
  - platform: neopixelbus
    num_leds: 189
    effects:
      - e131:
          universe: 1
          channels: RGB

配置变量：

universe（必选，int）：universe 的值，介于 1 到 512 之间。
channels（可选）：数据类型。用于指定它是 MONO、RGB 还是 RGBW 灯光以及颜色的顺序。默认为 RGB。

有三种工作模式：

MONO : 每个 LED 支持 1 个通道（亮度），每个 universe 最多 512 个 LED
RGB : 每个 LED 支持 3 个通道（RGB），每个 universe 最多 170 个 LED（3*170 = 510 字节）
RGBW : 每个 LED 支持 4 个通道（RGBW），每个 universe 最多 128 个 LED（4*128 = 512 字节）

如果 LED 数量多于每个 universe 允许的数量，将使用额外的 universe。在上述 189 个 LED 的示例中，前 170 个 LED 将分配给 universe 1，而剩余的 19 个 LED 将分配给 universe 2。

可以启用多个灯光平台同时监听同一个 universe，从而将行为复制到多个灯带上。

E1.31 组件

E1.31 效果需要 e131 灯光效果的组件中心。

配置变量：

method（可选）：监听方法，multicast 或 unicast 之一。默认为 multicast。

ESPHome 将监听 UDP 端口 5568。

Adalight 效果

此效果通过串行 Adalight 协议使可寻址灯光的控制成为可能，从而可以创建实时环境灯光效果。

Prismatik 可用于通过 ESPHome 上的 Adalight 协议控制可寻址灯光。

# 示例配置条目
# 禁用 USB 日志
logger:
  baud_rate: 0

# Adalight 需要更大的 RX 缓冲区
# 才能无闪烁地运行
uart:
  rx_buffer_size: 1024

adalight:

light:
  - platform: neopixelbus
    ...
    effects:
      - adalight:
          # uart_id: additional_uart

配置变量：

uart_id（可选，ID）：手动指定 UART Component 的 ID。如果你配置了多个 UART，则很有用。

WLED 效果

此效果通过使用 WLED 使用的 UDP Realtime Control 协议使可寻址灯光的控制成为可能，从而可以创建实时环境灯光效果。

Prismatik 和/或 LedFx 可用于在 ESPHome 上通过网络控制可寻址灯光。在默认端口上使用连接类型 udp 并添加数据前缀 0201。

wled:

light:
  - platform: neopixelbus
    ...
    effects:
      - wled:
          # port: 21324
          # blank_on_start: True
          # sync_group_mask: 0

配置变量：

port（可选，int）：运行 UDP 服务器的端口。默认为 21324。
blank_on_start（可选，boolean）：效果启动时是否将所有 LED 空白化。默认为 True。
sync_group_mask（可选，int）：与 WLED Notifier 一起使用。Sync Group 掩码值，用于指定要监听的 WLED Sync Groups。默认为 0（所有 Sync Groups）。Sync Groups 1、2、3、4、5、6、7、8 使用掩码 1、2、4、 8、16、32、64、128。组合掩码值以监听多个 Sync Groups。

NOTE

你也可以将 port 设为 19446，以与使用协议 0 的 UDP 设备的 Hyperion Classic 兼容。

支持以下实时协议：

WARLS
DRGB
DRGBW
DNRGB
WLED Notifier

Light 组件

基础 Light 配置

配置变量

Light 状态

Light 自动化

light.toggle 动作

light.turn_on 动作

light.turn_off 动作

light.control 动作

light.dim_relative 动作

light.effect.next / light.effect.previous 动作

light.addressable_set 动作

Light 条件

light.is_on / light.is_off 条件

Light 触发器

light.on_turn_on / light.on_turn_off 触发器

light.on_state 触发器

Light 效果

基础动画

灯带动画

外部控制

脉冲效果

随机效果

频闪效果

闪烁效果

Lambda 效果

访问效果名称

可寻址彩虹效果

可寻址颜色擦拭效果

可寻址扫描效果

可寻址闪烁效果

可寻址随机闪烁效果

可寻址烟花效果

可寻址闪烁效果

可寻址 Lambda 效果

自动化灯光效果

E1.31 效果

E1.31 组件

Adalight 效果

WLED 效果

参见

`light.toggle` 动作

`light.turn_on` 动作

`light.turn_off` 动作

`light.control` 动作

`light.dim_relative` 动作

`light.effect.next` / `light.effect.previous` 动作

`light.addressable_set` 动作

`light.is_on` / `light.is_off` 条件

`light.on_turn_on` / `light.on_turn_off` 触发器

`light.on_state` 触发器