企业官网建设流程全解析

Home Assistant LIFX 色彩循环效果完整指南：用 lifx.effect_colorloop 实现灯光自动循环变色

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io

lifx.effect_colorloop是 Home Assistant 为 LIFX 灯光提供的专用动作（action），用于运行一个基于软件的灯光效果：让灯光在色轮上持续循环变换颜色。本文以该动作的官方文档为骨架，结合 Home Assistant 源码仓库中的 LIFX 集成文档 与 light.turn_on 动作文档，完整讲解该效果的原理、UI 配置步骤、全部 YAML 参数与默认值、目标选择方式，以及与其他 LIFX 效果动作的配合使用。读完本文，你将能够在自动化与脚本中独立配置、调优并停止一个多灯协调的色彩循环效果。

Color Loop 效果是什么

Color loop（色彩循环）是一种基于软件的灯光效果（software-based effect）：灯光会在色轮上连续循环变换颜色。与硬件级效果（如 Flame、Morph、Sky、Move，它们只在特定 LIFX 设备上可用）不同，color loop 属于软件效果，由 Home Assistant 侧驱动，适用于常规的 LIFX 彩色灯泡。

该效果有一个值得注意的行为：当你同时目标多盏灯时，各灯之间会相互协调，保持相似但不完全相同的颜色。这一协调行为由spread（色相差异）参数控制，后文会详细说明。这一行为在官方文档中明确说明："When you target more than one light, they coordinate to keep similar, but not identical, colors."（参见 lifx.effect_colorloop 文档）。

快速启动：通过 light.turn_on 的 effect 属性

如果你只需要以默认参数启动色彩循环，不必使用专用动作。根据 LIFX 集成文档 与 light.turn_on 动作文档，普通light.turn_on动作的effect选项即可直接启动该效果，对应效果名称为lifx_effect_colorloop：

automation: alias: "Start a LIFX color loop" triggers: - trigger: state entity_id: binary_sensor.office_motion to: "on" actions: - action: light.turn_on target: entity_id: light.office data: effect: lifx_effect_colorloop

不过官方文档明确指出：light.turn_on的effect选项只能以默认选项启动效果；如果你要完全控制色彩循环的每一个参数（亮度、周期、色相变化量等），就必须使用专用的lifx.effect_colorloop动作。

从用户界面配置（UI 步骤）

在不写任何 YAML 的前提下，可以通过 Home Assistant 的自动化/脚本编辑器可视化配置该效果（参见 lifx.effect_colorloop 文档 中的 UI 操作步骤）：

1. 进入Settings（设置）> Automations & scenes（自动化与场景）。
2. 打开一个现有的自动化或脚本，或者选择Create automation（创建自动化）> Create new automation（创建新自动化）。
3. 如果是新建自动化，在When（何时）部分添加一个触发器；脚本不需要触发器，它们由其他流程调用时运行。
4. 在Then do（然后执行）部分选择Add action（添加动作）。
5. 选择要控制的对象：在By target（按目标）下选择要执行色彩循环的 LIFX 灯。
6. 在针对该目标显示的动作列表中，选择Color loop effect（色彩循环效果）。
7. 填写你想要使用的选项。
8. 选择Save（保存）。

UI 中可用的选项（Options in the UI）如下：

• Brightness value（亮度数值）：1 到 255 的数字，指定色彩循环的亮度；留空则保持各灯当前亮度。
• Brightness（亮度百分比）：亮度数值的替代方式，范围为 1 到 100 的百分比。
• Minimum saturation（最小饱和度）：循环中颜色允许的最小饱和度，1 到 100 的百分比。
• Maximum saturation（最大饱和度）：循环中颜色允许的最大饱和度，1 到 100 的百分比。
• Period（周期）：两次颜色变化之间的间隔，单位为秒。
• Transition（过渡）：灯光处于颜色变化过程中的持续时间，单位为秒。
• Change（变化量）：每个周期色相的移动量，单位为色轮上的度数（0 到 360）。
• Spread（色相差异）：参与循环的各灯之间允许的最大色相差，单位为色轮上的度数（0 到 360）。
• Power on（开启电源）：关闭此项可跳过处于关闭状态的灯上的效果。

YAML 用法与完整参数参考

在 YAML 中，该动作以lifx.effect_colorloop引用。基础示例如下（官方文档示例，原出处）：

action: lifx.effect_colorloop target: entity_id: light.living_room data: brightness: 180 period: 10 spread: 30 change: 35

这段配置会让客厅灯每 10 秒切换一次颜色，各参与灯之间的色相差异不超过 30 度，每个周期色相移动 35 度。

LIFX 集成文档中还给出了一个亮度更高的脚本示例（原出处）：

script: colorloop_start: alias: "Start colorloop" sequence: - action: lifx.effect_colorloop target: entity_id: light.livingroom data: brightness: 255 period: 10 spread: 30 change: 35

YAML 参数表（Options in YAML）

以下为lifx.effect_colorloop的全部 YAML 参数，包含类型、必填性与默认值，完整继承自 lifx.effect_colorloop 文档：

参数语义与调优建议

结合参数默认值与官方描述，可以这样理解每个参数的作用：

• saturation_min（默认 80）与saturation_max（默认 100）：共同界定循环中颜色饱和度的波动范围。默认区间较窄（80%–100%），意味着颜色始终非常鲜艳、接近纯色；如果想获得更柔和、更"粉彩"的视觉效果，可以调低saturation_min（例如 40）。
• period（默认 60）：控制换色节奏。10 秒偏"呼吸感"、节奏较快；60 秒则非常舒缓。
• change（默认 20）：每周期色相移动的度数。数值越大，相邻颜色差异越明显；360 度则相当于每周期绕色轮一整圈。
• spread（默认 30）：多灯协调的关键参数。多灯同时运行时，各灯会在spread限定的色相差范围内各取相似颜色；设 0 时所有灯颜色完全一致，设 360 时各灯可覆盖整个色轮。
• transition：与period配合使用——period决定"多久换一次色"，transition决定"换色过程持续多久"。
• power_on（默认 true）：默认情况下启动效果会顺带打开处于关闭状态的灯；设为false则只对已开灯生效，避免打扰处于关闭状态的灯光（例如睡眠时段的灯）。

动作的目标（Targets）

该动作需要指定目标（target）。目标是动作作用的对象，可以指向单个实体、设备、区域、楼层或标签，Home Assistant 会对该目标背后的每一个 light 实体执行动作（完整说明见 actions/targets.md 模板，其领域为light）：

• 实体（Entity）：某一个具体的 light 实体，如light.living_room。
• 设备（Device）：属于某一设备的所有 light 实体。
• 区域（Area）：某一房间/区域内的所有 light 实体。
• 楼层（Floor）：某一楼层上的所有 light 实体。
• 标签（Label）：共享某一标签的所有 light 实体。

同一个动作中可以混合不同目标类型，例如同时指定一个具体实体和一个区域。

与其他 LIFX 效果动作配合

lifx.effect_colorloop官方文档在related_actions中关联了两个动作（见文档 front matter）：

• lifx.effect_pulse：脉冲效果。灯光切换到某颜色后再回到原色，适合做通知提醒类闪烁。它同样支持brightness、brightness_pct、period、power_on等参数，并有mode（blink/breathe/ping/strobe/solid）、color_name、rgb_color、cycles等专属参数，默认mode: blink、period: 1.0、cycles: 1。
• lifx.effect_stop：停止效果。它运行一个"什么都不做"的效果，从而终止任何正在运行的软件或硬件效果，且不需要任何额外参数。用法示例：

action: lifx.effect_stop target: entity_id: light.living_room

一个典型组合是：lifx.effect_pulse在有人按门铃时闪烁提示，随后用lifx.effect_stop或再次调用lifx.effect_colorloop恢复氛围照明。

调试与验证：先试再写

在把效果写进自动化之前，可以直接在Settings（设置）> Tools（工具）> Actions（动作）中搜索该动作，填写字段并点击Perform action（执行动作）进行验证——无需编写任何 YAML（参见 actions/try_it.md 模板）。这是确认参数取值（尤其是period、change、spread的节奏感）是否满意的最高效方式。

如果效果未按预期工作，排查时可以关注以下几点：

• 确认目标实体确实属于 LIFX 集成且设备在线；LIFX 集成通过 Home Assistant 的网络配置自动发现同一子网内的灯泡，若灯泡在隔离的 IoT 网络中可能无法被发现，需要手动添加。
• 软件效果由 Home Assistant 侧持续驱动，若设备掉线或网络不稳，效果会中断。
• 若目标灯处于关闭状态而power_on为false，该灯会被跳过——这不是故障，而是预期行为。
• 需要立刻恢复静态灯光时，调用 lifx.effect_stop 即可。

总结

lifx.effect_colorloop是 Home Assistant 中实现 LIFX 灯光自动循环变色的标准途径：默认场景用light.turn_on的effect: lifx_effect_colorloop一步启动，需要精细控制亮度、周期、色相变化量与多灯色相差时则使用本专用动作。掌握period、transition、change、spread、saturation_min/max这几个核心参数与power_on的开关行为，再配合 lifx.effect_pulse 与 lifx.effect_stop，即可在自动化与脚本中构建完整的氛围灯光控制流程。

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io