Home Assistant light.toggle 动作完全指南：用单个动作在开与关之间切换灯光
【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io
light.toggle是 Home Assistant 中最实用的灯光控制动作之一：它让一盏灯在开与关之间翻转，不需要你先判断灯当前处于什么状态。本文以 Home Assistant 官方用户文档中 light.toggle 动作参考 为主体，系统讲解该动作在 UI 与 YAML 中的完整用法、全部参数、目标（Targets）机制，并结合仓库中的 light 域集成文档与动作模板源码，深入剖析其底层实现细节。读完本文，你将能独立写出按钮点按、人体感应、门磁联动等真实场景下的 toggle 自动化。
认识 Toggle light 动作
Toggle light动作会把灯光翻转到相反的状态：灯是关的，它就打开；灯是开的，它就关闭。这种“翻转”语义非常适合那些需要循环切换而无需关心当前状态的场景——最典型的就是一个物理按钮或一个人体传感器，按一下开、再按一下关，完全不需要你（或自动化）事先去查询灯现在的状态。
该动作自 Home Assistant 0.7 版本起就已存在（见文档 front matter 中的since: "0.7"），适用于任何 light 实体，包括单个灯泡、灯光分组、智能灯具乃至灯带。
一个关键行为需要特别注意：当 Toggle light 把灯打开时，你可以同时设置亮度、颜色、色温或过渡时间（transition），用法与 Turn on light 完全一致；而当 Toggle light 把灯关闭时，这些选项会被忽略。
Toggle 与 Turn on / Turn off 的选型
Toggle 并非总是最优解。当你已经明确知道想要的状态时，文档建议改用语义更清晰的动作：
- Turn on a light：打开灯光，可同时设置亮度、颜色、色温、效果或过渡。
- Turn off a light：关闭灯光，可选择淡出过渡或先闪烁提示。
使用light.turn_on/light.turn_off时，自动化名称本身就能表达意图，可读性更强；而light.toggle更适合“同一入口双向切换”的场景。这三个动作互为补充，在文档中互相列为 related actions。
在 UI 中使用 Toggle light
如果你偏好可视化配置，Home Assistant 会在设置 > 自动化与场景（Settings > Automations & scenes）中引导你逐步完成配置，无需任何 YAML 知识。在自动化或脚本中添加该动作的步骤如下：
- 进入设置 > 自动化与场景。
- 打开一个已有的自动化或脚本，或选择创建新建一个。
- 如果是新建自动化，在When（何时）部分添加触发器。脚本不需要触发器，它们由其他调用方触发运行。
- 在Then do（然后做）部分，选择添加动作（Add action）。
- 在搜索框中搜索并选择Toggle light。
- 在Targets（目标）下选择要切换的对象：
- 切换某一盏具体的灯：选择该实体（entity）；
- 切换房间内所有灯：选择区域（area）；
- 切换某一楼层所有灯：选择楼层（floor）；
- 切换共享某个标签的所有灯：选择标签（label）。
- 可选：在Additional options（附加选项）中设置灯被打开时应采用的亮度、颜色、色温或过渡时间。
- 选择保存。
UI 中的可用选项
| 选项 | 说明 | 必填 |
|---|---|---|
| Transition（过渡） | 灯达到新状态所需的时间（秒）。用于平滑渐变，而不是瞬间切换 | 否 |
| Brightness（亮度） | 灯被打开时的亮度，范围 0（关）到 255（最亮） | 否 |
| Brightness percentage（亮度百分比） | 灯被打开时的亮度百分比，0%（关）到 100%（最亮） | 否 |
| Color（颜色） | 灯被打开时的颜色。可选择命名颜色、色轮取色，或输入 RGB、hue/sat、XY 格式的具体值 | 否 |
| Color temperature（色温） | 暖白或冷白，以开尔文（Kelvin）为单位。数值越低越暖（偏黄），越高越冷（偏蓝） | 否 |
| Effect（效果） | 灯被打开时播放的效果，例如色彩循环或烛光闪烁。可用效果取决于具体灯具 | 否 |
| Flash（闪烁） | 让灯短暂闪烁，可选short或long。适合用作视觉通知 | 否 |
| Profile（配置文件） | 灯被打开时应用的灯光配置文件（light profile）名称 | 否 |
在 YAML 中使用 Toggle light
如果你直接使用 YAML，或想精确了解 Home Assistant 在底层做了什么，可以参考本节的完整技术参考。YAML 中该动作的调用名为light.toggle，基本示例如下：
action: light.toggle target: entity_id: light.hallway上面这段代码会把light.hallway翻转到相反状态。
YAML 中的完整参数参考
YAML 有时会提供 UI 中不可用的、更复杂场景的附加选项。light.toggle在 YAML 中的完整参数如下：
| 字段 | 类型 | 说明 | 必填 |
|---|---|---|---|
transition | integer | 达到下一状态所需的时间（秒）。用于平滑渐变而非瞬间切换 | 否 |
brightness | integer | 灯被打开时的亮度数值，0 为关，1 为最低，255 为最高 | 否 |
brightness_pct | integer | 灯被打开时的亮度百分比，0 为关，1 为最低，100 为最高 | 否 |
color_name | string | 人类可读的颜色名称，例如warm_white、tomato、cornflowerblue | 否 |
color_temp_kelvin | integer | 色温（开尔文）。数值越低越暖（偏黄），越高越冷（偏蓝） | 否 |
rgb_color | list | RGB 格式颜色，三个 0 到 255 之间的整数，分别代表红、绿、蓝 | 否 |
hs_color | list | hue/sat 格式颜色，两个整数：色相 0 到 360，饱和度 0 到 100 | 否 |
xy_color | list | XY 格式颜色，两个 0 到 1 之间的小数 | 否 |
effect | string | 灯被打开时应用的效果，可用效果取决于具体灯具 | 否 |
flash | string | 让灯短暂闪烁，接受short或long | 否 |
profile | string | 灯被打开时应用的灯光配置文件名称 | 否 |
Targets：动作的目标
light.toggle是一个**必须有目标（target）**的动作。目标就是动作作用的对象，你可以把动作指向单个实体、设备、区域、楼层或标签，Home Assistant 会对其背后所有匹配的 light 实体执行该动作：
- Entity（实体）：一个具体的 light 实体，例如
light.living_room。 - Device（设备）：属于某设备的所有 light 实体。
- Area（区域）：某个房间或区域内的所有 light 实体。
- Floor（楼层）：某个楼层上的所有 light 实体。
- Label（标签）：共享某个标签的所有 light 实体。
你也可以在同一个动作中混用不同类型的目标，例如同时添加一个具体实体和一个区域，让该动作对两者一起生效。这一机制来自动作文档公共模板 source/_includes/actions/targets.md，是 Home Assistant 所有动作页统一遵循的目标语义。
实战示例
以下是文档中提供的真实场景示例，可以直接复制并适配到你的环境中。
动作：单次按钮点按翻转走廊灯
将一个物理按钮或仪表盘磁贴连接到单个 toggle 动作上，让它像普通灯开关一样工作。
action: light.toggle target: entity_id: light.hallway动作：把厨房灯切换为暖白色调
当 toggle 把厨房灯打开时，让它以暗一些、暖一些的色调亮起，而不是全功率瞬间点亮。
action: light.toggle target: entity_id: light.kitchen data: brightness_pct: 40 color_name: warm_white这里同时用到了brightness_pct（40% 亮度）和color_name（warm_white暖白），它们只在灯被打开时生效。
自动化：用物理按钮切换走廊灯
在墙上放一个智能按钮，每次按下就翻转走廊灯——这是在原本没有开关的位置添加灯开关的好方法。
automation: alias: "Hallway button toggle" triggers: - trigger: state entity_id: event.hallway_button - trigger: event event_type: zha_event event_data: device_ieee: "00:11:22:33:44:55:66:77" command: "single" actions: - action: light.toggle target: entity_id: light.hallway注意这里提供了两种触发器写法（state 触发与 ZHA 事件触发），你可以根据自己按钮的接入方式二选一。
自动化：人体感应切换浴室灯
当浴室人体传感器触发时翻转灯光，下一次触发再翻回去——这样同一个自动化既能开灯也能关灯，离开时无需单独写关灯逻辑。
automation: alias: "Toggle bathroom light on motion" triggers: - trigger: state entity_id: binary_sensor.bathroom_motion to: "on" actions: - action: light.toggle target: entity_id: light.bathroom自动化：门磁联动切换储藏室灯
储藏室门打开时翻转灯光，下一次门再次打开时又把它关掉，开门即亮、随手即灭。
automation: alias: "Toggle pantry light on door" triggers: - trigger: state entity_id: binary_sensor.pantry_door to: "on" actions: - action: light.toggle target: entity_id: light.pantryGood to know：使用要点与注意事项
- 适用对象：Toggle light 动作适用于任何 light 实体，例如灯泡、分组、灯具或灯带。
- 打开时应用参数，关闭时忽略：当 Toggle light 把灯打开时，你设置的亮度、颜色或过渡会生效；当它把灯关闭时，这些选项被忽略。
- 对分组的行为：如果对一组灯使用 Toggle light，组内每盏灯会各自翻转自己的状态，可能出现“有的开、有的关”的结果。若想将一组灯当作一个整体来切换，请先创建一个专用的 light group。
- 状态明确时用 Turn on/off：如果你已经知道目标状态，建议改用 Turn on a light 或 Turn off a light，这样自动化名称中的意图更清晰。
源码视角：light 域如何支撑 toggle 的底层语义
为了准确理解light.toggle背后发生的事，可以结合仓库中 light 域集成文档 source/_integrations/light.markdown 来看：
状态与属性。light 实体只可能处于on或off两种状态，可用属性列表取决于具体设备。toggle 的本质就是在on与off之间翻转这个状态机。
默认开灯值（light profiles）。如果你希望灯被打开时总是采用一组默认的颜色、亮度和过渡值，可以在配置目录（与configuration.yaml同目录）下创建自定义的light_profiles.csv。该文件必须包含表头，格式如下：
id,x,y,brightness,transitionid：配置文件名称，用于在动作调用中引用。x/y：CIE 1931 色彩空间（xy color）的坐标，通常为 0 到 1 之间的浮点数。这正是 YAML 参数xy_color的物理基础。brightness：要应用的亮度级别，为 0 到 255 的字节值（注意不是百分比）。transition：可选的正整数，指定灯渐变到新状态的过渡时间（秒），该列可以省略。
要给某盏灯定义默认值，需要在实体标识符后加上.default后缀。例如对light.ceiling_2，profile字段应写成light.ceiling_2.default；若要为所有灯定义默认值，可使用group.all_lights.default。单灯设置始终优先于all_lights全局默认值。
值得特别注意的是文档中的这条说明：过渡（transition）属性会应用于所有light.turn_on、light.toggle和light.turn_off动作，除非在动作数据中另行指定；而如果灯已处于on状态，默认配置文件的亮度只会在动作数据中以profile属性显式调用时才会应用。这意味着你可以在light_profiles.csv中统一配置淡入淡出过渡，light.toggle也会自动遵守，从而实现“开关灯都平滑渐变”的整体体验。
动作索引与可发现性。整个动作体系由 source/actions/index.html 统一呈现：所有source/_actions/下的动作文档按 domain 分组、支持搜索，每个动作页都包含逐步 UI 引导、示例和完整数据字段参考。light.toggle与light.turn_on、light.turn_off同属 light 域，在相关动作（related actions）中互相链接（见 source/_includes/actions/related.md）。
立即上手测试
想快速验证？打开设置 > 工具 > 动作（Settings > Tools > Actions），搜索该动作，填写字段并选择执行动作（Perform action）。你可以在真实实体上立即看到效果，无需编写任何 YAML（见 source/_includes/actions/try_it.md）。
遇到问题时可从三方面自查：确认目标实体 ID 正确、确认灯光硬件支持你所设置的字段（不支持颜色能力的灯泡会静默忽略颜色字段）、确认在 toggle 关闭方向上的参数确实被忽略——这些都是文档与源码中明确的行为约定。
【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
