Home Assistant light.toggle 动作完全指南用单个动作在开与关之间切换灯光【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.iolight.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 中的完整参数如下字段类型说明必填transitioninteger达到下一状态所需的时间秒。用于平滑渐变而非瞬间切换否brightnessinteger灯被打开时的亮度数值0 为关1 为最低255 为最高否brightness_pctinteger灯被打开时的亮度百分比0 为关1 为最低100 为最高否color_namestring人类可读的颜色名称例如warm_white、tomato、cornflowerblue否color_temp_kelvininteger色温开尔文。数值越低越暖偏黄越高越冷偏蓝否rgb_colorlistRGB 格式颜色三个 0 到 255 之间的整数分别代表红、绿、蓝否hs_colorlisthue/sat 格式颜色两个整数色相 0 到 360饱和度 0 到 100否xy_colorlistXY 格式颜色两个 0 到 1 之间的小数否effectstring灯被打开时应用的效果可用效果取决于具体灯具否flashstring让灯短暂闪烁接受short或long否profilestring灯被打开时应用的灯光配置文件名称否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_pct40% 亮度和color_namewarm_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/yCIE 1931 色彩空间xy color的坐标通常为 0 到 1 之间的浮点数。这正是 YAML 参数xy_color的物理基础。brightness要应用的亮度级别为 0 到 255 的字节值注意不是百分比。transition可选的正整数指定灯渐变到新状态的过渡时间秒该列可以省略。要给某盏灯定义默认值需要在实体标识符后加上.default后缀。例如对light.ceiling_2profile字段应写成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），仅供参考