光实体#

灯光实体控制光源的亮度、色调和饱和度颜色值、白色值、色温和效果。平台实体派生自homeassistant.components.light.LightEntity。

#特性

#色彩模式

新集成必须同时实现 color_mode 和 supported_color_modes。如果集成升级为支持颜色模式，则应同时实现 color_mode 和 supported_color_modes。

支持的颜色模式是通过使用 ColorMode 枚举中的值来定义的。

如果灯光未实现 supported_color_modes，则 LightEntity 将尝试根据 supported_features 属性中已弃用的标志来推断它：

• 从一个空集开始
• 如果设置了 SUPPORT_COLOR_TEMP，则添加 ColorMode.COLOR_TEMP
• 如果设置了 SUPPORT_COLOR，则添加 ColorMode.HS
• 如果设置了 SUPPORT_WHITE_VALUE，则添加 ColorMode.RGBW
• 如果设置了 SUPPORT_BRIGHTNESS 并且尚未添加颜色模式，请添加 ColorMode.BRIGHTNESS
• 如果尚未添加颜色模式，请添加 ColorMode.ONOFF

如果灯光未实现 color_mode，LightEntity 将尝试根据设置的属性和 None 的属性来推断它：

• 如果 supported_color_modes 包含 ColorMode.RGBW 并且 white_value 和 hs_color 都不为 None：ColorMode.RGBW
• 否则，如果 supported_color_modes 包含 ColorMode.HS 并且 hs_color 不为 None：ColorMode.HS
• 否则，如果 supported_color_modes 包含 ColorMode.COLOR_TEMP 并且 color_temp 不为 None：ColorMode.COLOR_TEMP
• 否则，如果 supported_color_modes 包含 ColorMode.BRIGHTNESS 并且 brightness 不为 None：ColorMode.BRIGHTNESS
• 否则如果 supported_color_modes 包含 ColorMode.ONOFF: ColorMode.ONOFF
• 其他：ColorMode.UNKNOWN

请注意，在颜色模式 ColorMode.RGB、ColorMode.RGBW 和 ColorMode.RGBWW 中，灯光的 brightness 属性和颜色中都有亮度信息。例如，如果灯光的亮度为 128，灯光的颜色为 (192, 64, 32)，则灯光的整体亮度为：128/255 * max(192, 64, 32)/255 = 38%。

如果灯光处于 ColorMode.HS、ColorMode.RGB 或 ColorMode.XY 模式，则灯光的状态属性将包含以 hs、rgb 和 xy 颜色格式表示的灯光颜色。请注意，当灯光处于 ColorMode.RGB 模式时，hs 和 xy 状态属性仅保存 rgb 颜色的色度，因为 hs 和 xy 对不保存亮度信息。

如果灯光处于 ColorMode.RGBW 或 ColorMode.RGBWW 模式，则灯光的状态属性将包含以 hs、rgb 和 xy 颜色格式表示的灯光颜色。颜色转换是通过将白色通道添加到颜色中来完成的近似值。

#白色模式

有两种白色模式：ColorMode.COLOR_TEMP 和 ColorMode.WHITE。两种模式之间的区别在于 ColorMode.WHITE 不允许调整色温，而 ColorMode.COLOR_TEMP 允许调整色温。

色温可调的灯通常由至少两组具有不同色温的LED来实现，通常是一组暖白光LED和一组冷白光LED。 色温不可调节的灯通常只有一组白色 LED。

#渲染效果时的颜色模式

渲染效果时，color_mode应根据支持的调整进行设置 影响。如果效果不支持任何调整，则 color_mode 应设置为 ColorMode.ONOFF。 如果效果允许调节亮度，则color_mode应设置为ColorMode.BRIGHTNESS。

渲染效果时，可以将 color_mode 设置为比颜色模式更严格的模式 由 supported_color_mode 属性表示：

• 当受效果控制时，支持颜色的灯光可以将 color_mode 设置为 ColorMode.ONOFF 或 ColorMode.BRIGHTNESS
• 支持亮度的灯光在受效果控制时可以将 color_mode 设置为 ColorMode.ONOFF

#支持的功能

支持的功能通过使用 LightEntityFeature 枚举中的值来定义 和 使用按位或 (|) 运算符进行组合。

#方法

#打开灯光设备

class MyLightEntity(LightEntity):
    def turn_on(self, **kwargs):
        """Turn the device on."""

    async def async_turn_on(self, **kwargs):
        """Turn device on."""

请注意，没有 color_mode 传递给 async_turn_on 方法，而是只允许单个颜色属性。 确保集成仅在 turn_on 调用中接收单一颜色属性，根据灯光的 supported_color_modes 属性保证该灯光支持该颜色属性。为了确保这一点，如果灯光不支持相应的颜色模式，则在调用实体的 async_turn_on 方法之前，将转换服务操作调用中的颜色：

:::tip 缩放亮度

Home Assistant 包含一个调节亮度的实用程序。

如果灯光支持亮度，有时亮度值需要缩放：

from homeassistant.util.color import value_to_brightness

BRIGHTNESS_SCALE = (1, 1023)

...

    @property
    def brightness(self) -> Optional[int]:
        """Return the current brightness."""
        return value_to_brightness(BRIGHTNESS_SCALE, self._device.brightness)

要将亮度缩放到设备范围：

from homeassistant.util.color import brightness_to_value
BRIGHTNESS_SCALE = (1, 1023)

...

class MyLightEntity(LightEntity):
    async def async_turn_on(self, **kwargs) -> None:
        """Turn device on."""

        ...

        value_in_range = math.ceil(brightness_to_value(BRIGHTNESS_SCALE, kwargs[ATTR_BRIGHTNESS]))

:::

### Turn Off Light Device

```python
类 MyLightEntity(LightEntity):
defturn_off(self, **kwargs):
“”“关闭设备。”“”

异步 def async_turn_off(self, **kwargs):
“”“关闭设备。”“”