企业官网建设流程全解析

Home Assistant Yeelight 色温场景动作 yeelight.set_color_temp_scene 完全指南

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

yeelight.set_color_temp_scene是 Home Assistant Yeelight 集成提供的场景类动作，一条指令即可把 Yeelight 灯具设置为指定的色温（Kelvin）与亮度（Brightness）组合，并在灯具处于关闭状态时自动将其点亮。本文将以 source/_actions/yeelight.set_color_temp_scene.markdown 为核心，结合 Yeelight 集成文档 与同系列场景动作，完整讲解该动作在自动化/脚本中的图形界面操作、YAML 配置、目标（Target）选择方式，以及背后的色温数值边界与固件实现细节，帮助你一键复现"晚间暖光""专注工作冷光"等常用白光场景。

动作概览：一条指令复现你偏好的白光

场景（Scene）与普通调节指令的区别在于：场景一次性地把灯具带到一组完整、可复现的光效状态，而不需要多条指令组合。yeelight.set_color_temp_scene正是这样的动作——它同时设定色温与亮度两个维度：

• 若灯具当前处于关闭状态，执行该动作会自动将其打开，并直接落到目标白光状态；
• 若灯具已开启，则立即切换到目标色温与亮度。

典型的使用场景就是"记忆一种偏好的白光色调"：

• 晚间放松：偏暖的低色温白光（如 2700 K），营造温馨氛围；
• 白天专注工作：偏冷的高色温白光（如 5000 K 以上），提供更清醒的照明感受。

从命名上可以看出，它是 Yeelight 集成"场景（Scene）"动作家族的一员。该家族还包括设置 RGB 颜色的 yeelight.set_color_scene、按 HSV 设置的 yeelight.set_hsv_scene、定时关灯的 yeelight.set_auto_delay_off_scene 以及动态流光 yeelight.set_color_flow_scene，它们共享同一套"目标 + 数据"的调用模型，学习这一个即可触类旁通。

前置条件：先完成 Yeelight 集成配置

在使用本动作前，需要确保你的 Yeelight 灯具已经接入 Home Assistant。根据 Yeelight 集成文档，集成具备以下特性：

• 配置流（Config Flow）：支持通过 UI 向导添加设备，也可以使用 Zeroconf、DHCP 自动发现；
• IoT 类型为 Local Push：灯具状态变化由本地推送，无需云服务；
• 支持Light与Binary sensor两类平台，其中二进制传感器目前仅用于吸顶灯的夜灯模式检测。

需要注意的初始化要求是：必须先用 Yeelight 官方 App 在灯具属性中开启"LAN Control"（旧称 "Developer mode"，即局域网控制），并确认灯具固件为最新版本；该开关决定了 Home Assistant 是否能够通过局域网 API 控制灯具。若你的灯具型号较旧且不支持 mDNS 自动发现（例如部分 Mijia 桌面灯），则需要在configuration.yaml中按 IP 手动声明设备。

通过图形界面（UI）使用该动作

如果你习惯可视化地构建自动化与脚本，Home Assistant 会引导你逐步完成配置，无需手写 YAML。操作步骤如下：

1. 进入设置 > 自动化与场景（Settings > Automations & scenes）；
2. 打开一个已有的自动化或脚本，或选择创建自动化 > 创建新自动化；
3. 如果是从零创建新自动化，先在When（何时）部分添加触发器；脚本（Script）不需要触发器，它们由其他自动化或指令显式调用；
4. 在Then do（然后执行）部分选择添加动作；
5. 在目标（By target）下选择要控制的 Yeelight 灯具（目标概念见下文 目标（Targets） 小节）；
6. 在该目标可用的动作列表中选择Set color temperature scene（设置色温场景）；
7. 填写Kelvin（色温）与Brightness（亮度）两个参数；
8. 点击保存。

UI 中的可选项

其中色温下限 1700 K 对应暖黄光，上限 6500 K 对应偏蓝的冷白光，这正是 Yeelight 灯具所支持的白光色温区间。

在 YAML 中使用该动作

如果你直接在 YAML 中编写自动化，或者想精确了解 Home Assistant 在底层做了什么，可以使用如下字段级参考。在 YAML 中，该动作的标识符为yeelight.set_color_temp_scene。基础示例如下：

action: yeelight.set_color_temp_scene target: entity_id: light.living_room data: kelvin: 2700 brightness: 80

将这个动作放进一个完整的自动化示例中：

alias: "Living room warm evening light" triggers: - trigger: sun event: sunset actions: - action: yeelight.set_color_temp_scene target: entity_id: light.living_room data: kelvin: 2700 brightness: 80 mode: single

YAML 中的可选项

注意data中两个字段均必填，缺一不可；动作执行时会一次性下发色温与亮度，灯具会呈现为"该色温下的该亮度"这一确定状态。若需要平滑过渡而非瞬间切换，可以在灯具的设备配置中设置transition选项（见下文"源码与配置细节"）。

目标（Targets）

该动作必须指定一个目标。目标是动作的作用对象，你可以把动作指向单个实体、设备、区域、楼层或标签，Home Assistant 会对其背后所有匹配的light实体执行该动作。可选的目标类型包括：

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

同一动作中还可以混合多种目标类型，例如同时添加一个具体实体和一个区域，让该动作同时作用于两者——这在"回家时把客厅与走廊灯统一调成暖光"这类场景中非常实用。

深入：色温数值边界的实现依据

为什么kelvin的取值范围是 1700 ～ 6500？从 Yeelight 集成文档 的自定义效果（Custom effects）与完整配置部分可以看到一致的定义：

• TemperatureTransition：[temp, duration, brightness]，其中temp为最终色温，介于 1700 与 6500 之间，duration为过渡时长（毫秒，最小 50），brightness为最终亮度（1-100%）；
• 集成还支持RGBTransition（RGB 值 0-255）、HSVTransition（色相 0-359、饱和度 0-100）与SleepTransition（仅时长）。

也就是说，色温场景动作的 1700–6500 K 边界与灯具底层 API 的色温能力区间完全一致，Home Assistant 只是把这个硬件能力直接暴露为动作参数。

此外，集成配置中的model选项（可能取值为mono1、color1、color2、strip1、bslamp1、ceiling1～ceiling13等）说明："该设置用于启用型号特定的功能，例如特定的色温范围"。因此从源码结构看，不同型号的 Yeelight 灯具实际可用的色温区间可能存在差异，1700–6500 K 是动作接口允许的通用范围，具体灯具的表现以其固件与型号为准。

同系列场景动作：何时选用哪个

Yeelight 场景动作家族共享相同的"目标 + 必填参数"结构，按你需要的灯光维度选择即可：

其中set_color_flow_scene与 yeelight.start_flow 接受相同的transitions列表（如TemperatureTransition: [1900, 1000, 80]这类数组），但前者走的是 Yeelight 的SceneAPI 调用且会在灯具关闭时自动点亮，后者走Start FlowAPI 调用；文档同时提示，不同固件在处理复杂流时的表现可能存在差异。

快速验证：在不写 YAML 的情况下试跑

想立刻验证效果？打开设置 > 工具 > 动作（Settings > Tools > Actions），搜索yeelight.set_color_temp_scene，直接填写字段并点击执行动作（Perform action），即可在真实灯具上观察效果，全程无需编写一行 YAML。这对于确定某个色温/亮度组合是否符合预期、再决定是否写进自动化，是最快的验证路径。

小结

yeelight.set_color_temp_scene是 Home Assistant 中"一键复现偏好白光"的标准动作：UI 与 YAML 两条路径完全等价，核心只需把握kelvin（1700–6500）与brightness（1–100）两个必填参数，配合实体/设备/区域/楼层/标签多级目标机制，即可在自动化中优雅地统一控制一盏或多盏 Yeelight 灯具的白光状态。若想进一步扩展，可参考 Yeelight 集成文档 中的transition平滑过渡、save_on_change状态保存以及custom_effects自定义流光配置，把简单的色温场景升级为更丰富的照明体验。

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