Light entity#

Light entity 控制 light source 的 brightness、hue 和 saturation color value、white value、color temperature 和 effect。从 homeassistant.components.light.LightEntity 派生 platform entities。

#属性

#颜色模式

Light 必须同时实现 color_mode 和 supported_color_modes。Supported color modes 通过使用 ColorMode 枚举中的值来定义，color_mode 必须设为 supported_color_modes 中列出的 modes 之一。

设置 supported_color_modes 是必需的。未设置它的 light 在写入 state 时会引发 error。

可用的 color modes 有：

注意，在 color modes ColorMode.RGB、ColorMode.RGBW 和 ColorMode.RGBWW 中，brightness property 和 color 中都包含 brightness 信息。例如，如果 light 的 brightness 是 128 且 light 的 color 是 (192, 64, 32)，light 的整体 brightness 为：128/255 * max(192, 64, 32)/255 = 38%。

如果 light 处于 ColorMode.HS、ColorMode.RGB 或 ColorMode.XY mode，light 的 state attribute 将包含用 hs、rgb 和 xy color 格式表示的 light color。注意，当 light 处于 ColorMode.RGB mode 时，hs 和 xy state attributes 仅保留 rgb color 的 chromaticity，因为 hs 和 xy pair 不包含 brightness 信息。

如果 light 处于 ColorMode.RGBW 或 ColorMode.RGBWW mode，light 的 state attribute 将包含用 hs、rgb 和 xy color 格式表示的 light color。Color 转换是通过将 white channel 加到 color 上来近似完成的。

#白色颜色模式

有两种 white color modes：ColorMode.COLOR_TEMP 和 ColorMode.WHITE。两种 mode 的区别在于 ColorMode.WHITE 不允许调整 color temperature，而 ColorMode.COLOR_TEMP 允许调整 color temperature。

具有可调整 color temperature 的 lamp 通常由至少两组 LED 实现，具有不同的 color temperature，通常是一组 warm-white LED 和一组 cold-white LED。 具有不可调整 color temperature 的 light 通常只有一组 white LED。

#渲染 effect 时的 color mode

在渲染 effect 时，应根据 effect 支持的调整来设置 color_mode。如果 effect 不支持任何调整，color_mode 应设为 ColorMode.ONOFF。 如果 effect 允许调整 brightness，color_mode 应设为 ColorMode.BRIGHTNESS。

在渲染 effect 时，允许将 color_mode 设为比 supported_color_mode property 指示的更 restrictive 的 mode：

• 支持 color 的 light 在由 effect 控制时可以将其 color_mode 设为 ColorMode.ONOFF 或 ColorMode.BRIGHTNESS
• 支持 brightness 的 light 在由 effect 控制时可以将其 color_mode 设为 ColorMode.ONOFF

#支持的功能

Supported features 通过使用 LightEntityFeature 枚举中的值来定义， 并使用按位或（|）运算符组合。

#方法

#开启 light device

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

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

注意，传递给 async_turn_on method 时没有 color_mode，而是只允许单个 color attribute。 保证 integration 在 turn_on call 中只会收到单个 color attribute，并且根据 light 的 supported_color_modes property，保证它被 light 支持。为确保这一点，如果 light 不支持相应的 color mode，service action call 中的 color 会在调用 entity 的 async_turn_on method 之前进行转换：

:::tip Scaling brightness

Home Assistant 包含用于 scale brightness 的 utility。

如果 light 支持 brightness，有时 brightness value 需要 scaling：

from homeassistant.util.color import value_to_brightness

BRIGHTNESS_SCALE = (1, 1023)

...

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

将 brightness scale 到 device range：

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

...

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

        ...

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

:::

### 关闭 light device

```python
class MyLightEntity(LightEntity):
    def turn_off(self, **kwargs: Any) -> None:
        """Turn the device off."""

    async def async_turn_off(self, **kwargs: Any) -> None:
        """Turn device off."""