Entity#

关于实体的通用介绍，请参见 entities architecture。

#基础实现

下面是一个 switch entity 的示例，它在内存中跟踪其 state。 此外，示例中的 switch 代表设备的主要 feature， 意味着 entity 与其 device 同名。

请查阅 Entity naming 了解如何为 entity 设置自己的名称。

from homeassistant.components.switch import SwitchEntity


class MySwitch(SwitchEntity):
    _attr_has_entity_name = True

    def __init__(self):
        self._is_on = False
        self._attr_device_info = ...  # 用于自动 device 注册
        self._attr_unique_id = ...

    @property
    def is_on(self):
        """If the switch is currently on or off."""
        return self._is_on

    def turn_on(self, **kwargs):
        """Turn the switch on."""
        self._is_on = True

    def turn_off(self, **kwargs):
        """Turn the switch off."""
        self._is_on = False

构建一个 switch entity 就这么多内容！继续阅读以了解更多，或者查看 视频教程。

#更新 entity

Entity 代表一个 device。有多种策略可以让你的 entity 与 device 的 state 保持同步，其中最常用的是 polling。

#轮询

在 polling 模式下，Home Assistant 会定时（取决于 component 的更新间隔）向 entity 请求最新的 state。当 should_poll 属性返回 True（默认值）时，Home Assistant 会轮询该 entity。你可以使用 update() 或异步方法 async_update() 来实现更新逻辑。该方法应从 device 获取最新的 state，并将其存储在 instance variable 中，以便 properties 返回它。

#订阅更新

当你订阅 updates 时，你的代码需要负责通知 Home Assistant 有新的更新可用。请确保 should_poll 属性返回 False。

每当通过订阅收到新的 state 时，你可以通过调用 schedule_update_ha_state() 或异步回调 async_schedule_update_ha_state() 来通知 Home Assistant 有更新可用。如果希望 Home Assistant 在将更新写入 Home Assistant 之前先调用你的 update method，请将布尔值 True 传入该方法。

#通用属性

Entity 基类有一些在所有 Home Assistant entity 中通用的属性。这些属性可以添加到任何 entity 中，无论其类型如何。所有这些属性都是可选的，不需要实现。

这些属性在 state 写入 state machine 时总是会被调用。

#Registry 属性

以下属性用于填充 entity 和 device registries。每次 entity 被添加到 Home Assistant 时都会读取它们。这些属性只有在 unique_id 不为 None 时才会生效。

#附加属性

以下属性也可用于 entity，但应谨慎使用。这些属性在 state 写入 state machine 时总是会被调用。

#系统属性

以下属性由 Home Assistant 使用和控制，集成不应 override。

#Entity 命名

避免将 entity 的名称设置为硬编码的英文字符串，而是，名称应该被 translated。名称不应被翻译的示例包括专有名词、model 名称以及由第三方库提供的名称。

一些 entity 会根据其 device class 自动命名，这包括 binary_sensor、button、number 和 sensor entity，在许多情况下不需要命名。 例如，一个未命名且 device class 设为 temperature 的 sensor 将被命名为 "Temperature"。

#has_entity_name True（新集成必需）

Entity 的 name 属性只标识 entity 所代表的数据点，不应包含 device 名称或 entity 类型。因此，对于代表其 device 功耗的 sensor，这应该是 "Power usage"。

如果 entity 代表 device 的单一主要 feature，该 entity 的 name 属性通常应返回 None。 Device 的"主要 feature"例如是智能灯泡的 LightEntity。

friendly_name state attribute 通过将 entity name 与 device name 组合生成，规则如下：

• Entity 不是 device 的成员：friendly_name = entity.name
• Entity 是 device 的成员且 entity.name 不为 None：friendly_name = f"{device.name} {entity.name}"
• Entity 是 device 的成员且 entity.name 为 None：friendly_name = f"{device.name}"

entity_id 通过将 entity name 与 device name 组合生成，规则如下：

• Entity 不是 device 的成员，例如 helper "Everyone is home"：entity_id = binary_sensor.everyone_is_home
• Entity 是 device 的成员且 entity.name 不为 None，例如名为 "nightlight" 的 device 的电池：entity_id = sensor.nightlight_battery
• Entity 是 device 的成员且 entity.name 为 None，例如名为 "nightlight" 的 device 的 light：entity_id = light.nightlight

Entity name 应以大写开头，其余单词为小写（除非是专有名词或大写缩写）。

#作为 device 主要 feature 的 switch entity 示例

注意：示例使用类属性实现 properties，其他实现方式请参见 Property implementation。 注意：示例不完整，必须实现 unique_id 属性，并且 entity 必须 与 device 注册。

from homeassistant.components.switch import SwitchEntity


class MySwitch(SwitchEntity):
    _attr_has_entity_name = True
    _attr_name = None

#作为非 device 主要 feature 或非 device 一部分的 switch entity 示例：

注意：示例使用类属性实现 properties，其他实现方式 请参见 Property implementation。 注意：如果 entity 是 device 的一部分，必须实现 unique_id 属性，并且 entity 必须 与 device 注册。

from homeassistant.components.switch import SwitchEntity


class MySwitch(SwitchEntity):
    _attr_has_entity_name = True

    @property
    def translation_key(self):
        """Return the translation key to translate the entity's name and states."""
        return "my_switch"

#非翻译的 switch entity 示例（非 device 主要 feature 或非 device 一部分）：

from homeassistant.components.switch import SwitchEntity


class MySwitch(SwitchEntity):
    _attr_has_entity_name = True

    @property
    def name(self):
        """Name of the entity."""
        return "Model X"

#has_entity_name 未实现或为 False（已弃用）

Entity 的 name 属性可以是 device 名称与 entity 所代表的数据点的组合。

#Property 实现

#Property 函数

为每个 property 编写 property method 只需要几行代码， 例如

class MySwitch(SwitchEntity):

    @property
    def icon(self) -> str | None:
        """Icon of the entity."""
        return "mdi:door"

    ...

#Entity 类属性或实例属性

另一种较短的形式是，按照以下任一模式设置 Entity 类属性或实例属性：

class MySwitch(SwitchEntity):

    _attr_icon = "mdi:door"

    ...

class MySwitch(SwitchEntity):

    def __init__(self, icon: str) -> None:
        self._attr_icon = icon

    ...

这与第一个示例完全相同，但依赖于基类中 property 的默认 实现。该属性的名称以 _attr_ 开头，后跟 property 名称。例如，默认 的 device_class property 返回 _attr_device_class 类属性。

并非所有 entity 类都支持使用 _attr_ 属性来实现其 entity 特定属性，请参阅相应 entity 类的文档以获取详细信息。

#Entity 描述

设置 entity property 的第三种方法是使用 entity description。为此，请在 Entity 实例上设置一个名为 entity_description 的属性，其值为 EntityDescription 实例。Entity description 是一个 dataclass，其 attributes 对应于大多数可用的 Entity properties。每个支持 entity platform 的 entity 集成（例如 switch 集成）都会定义自己的 EntityDescription 子类，使用 entity descriptions 的实现 platform 应使用该子类。

默认情况下，EntityDescription 实例有一个必需的 attribute 名为 key。这是一个字符串，旨在对实现 platform 的所有 entity descriptions 保持唯一。该 attribute 的一个常见用例是将其包含在描述 entity 的 unique_id 中。

使用 entity descriptions 的主要好处是，它以一种声明式的方式定义了 platform 的不同 entity types，当存在许多不同 entity type 时，这使得代码更易读。

#示例

下面的代码片段示例说明了何时应实现 property 函数、何时使用类属性或实例属性以及何时使用 entity descriptions 的最佳实践。

from __future__ import annotations

from collections.abc import Callable
from dataclasses import dataclass

from example import ExampleDevice, ExampleException

from homeassistant.components.sensor import (
    SensorDeviceClass,
    SensorEntity,
    SensorEntityDescription,
    SensorStateClass,
)
from homeassistant.config_entries import ConfigEntry
from homeassistant.const import (
    EntityCategory,
    UnitOfElectricCurrent,
)
from homeassistant.core import HomeAssistant
from homeassistant.helpers.entity_platform import AddConfigEntryEntitiesCallback
from homeassistant.helpers.typing import StateType

from .const import DOMAIN, LOGGER


@dataclass(kw_only=True)
class ExampleSensorEntityDescription(SensorEntityDescription):
    """Describes Example sensor entity."""

    exists_fn: Callable[[ExampleDevice], bool] = lambda _: True
    value_fn: Callable[[ExampleDevice], StateType]


SENSORS: tuple[ExampleSensorEntityDescription, ...] = (
    ExampleSensorEntityDescription(
        key="estimated_current",
        native_unit_of_measurement=UnitOfElectricCurrent.MILLIAMPERE,
        device_class=SensorDeviceClass.CURRENT,
        state_class=SensorStateClass.MEASUREMENT,
        value_fn=lambda device: device.power,
        exists_fn=lambda device: bool(device.max_power),
    ),
)


async def async_setup_entry(
    hass: HomeAssistant,
    entry: ConfigEntry,
    async_add_entities: AddConfigEntryEntitiesCallback,
) -> None:
    """Set up Example sensor based on a config entry."""
    device: ExampleDevice = entry.runtime_data
    async_add_entities(
        ExampleSensorEntity(device, description)
        for description in SENSORS
        if description.exists_fn(device)
    )


class ExampleSensorEntity(SensorEntity):
    """Represent an Example sensor."""

    entity_description: ExampleSensorEntityDescription
    _attr_entity_category = (
        EntityCategory.DIAGNOSTIC
    )  # 这对所有 ExampleSensorEntity 实例是通用的

    def __init__(
        self, device: ExampleDevice, entity_description: ExampleSensorEntityDescription
    ) -> None:
        """Set up the instance."""
        self._device = device
        self.entity_description = entity_description
        self._attr_available = False  # 这会覆盖默认值
        self._attr_unique_id = f"{device.serial}_{entity_description.key}"

    def update(self) -> None:
        """Update entity state."""
        try:
            self._device.update()
        except ExampleException:
            if self.available:  # 读取当前 state，不需要加 _attr_ 前缀
                LOGGER.warning("Update failed for %s", self.entity_id)
            self._attr_available = False  # 设置 property 值
            return

        self._attr_available = True
        # 这里不需要检查 device 是否可用
        self._attr_native_value = self.entity_description.value_fn(
            self._device
        )  # 更新 "native_value" property

#生命周期钩子

使用这些 lifecycle hooks 在发生某些事件时执行代码。所有 lifecycle hooks 都是异步方法。

#async_added_to_hass()

当 entity 被分配 entity_id 和 hass 对象后，且第一次写入 state machine 之前调用。示例用途：恢复 state、订阅 updates 或设置 callback/dispatch function/listener。

#async_will_remove_from_hass()

当 entity 即将从 Home Assistant 移除时调用。示例用途：断开与 server 的连接或取消订阅 updates。

#图标

Home Assistant 中的每个 entity 都有一个 icon，用作前端中更易识别 entity 的视觉指示器。Home Assistant 使用 Material Design Icons icon 集。

在大多数情况下，Home Assistant 会根据 entity 的 domain、device_class 和 state 自动选择一个 icon。如果可能，优先使用默认 icon，以提供一致的体验并避免用户混淆。但是，也可以 override 默认值并为 entity 提供自定义 icon。

无论提供什么 icon，用户总可以在前端按照自己的喜好自定义 icon。

有两种方式为 entity 提供自定义 icon：通过提供 icon translations 或通过提供 icon identifier。

#图标翻译

这是为 entity 提供自定义 icon 的首选方式。Icon translations 的工作方式类似于 常规 translations，但它们不是翻译 entity 的 state，而是将 entity 的 states 翻译为 icons。

请注意，translated states 必须像所有其他 translation key 一样是 snake_case。

Entity 的 translation_key 属性定义了要使用的 icon translation。该属性用于在集成的 icons.json 文件的 entity section 中查找 translation。

为了区分 entity 及其 translations，请提供不同的 translation keys。以下示例展示了 Moon domain sensor entity 的 icons.json，其 translation_key 属性设为 phase：

{
  "entity": {
    "sensor": {
      "phase": {
        "default": "mdi:moon",
        "state": {
          "new_moon": "mdi:moon-new",
          "first_quarter": "mdi:moon-first-quarter",
          "full_moon": "mdi:moon-full",
          "last_quarter": "mdi:moon-last-quarter"
        }
      }
    }
  }
}

请注意，icons 以 mdi: 开头，后跟一个 identifier。当 entity 的 state 不在 state section 中时，使用 default icon。state section 是可选的，如果未提供，default icon 将用于所有 states。

在前端显示 state attributes 的 icons 时，也可以为 entity state attributes 提供 icons。示例包括 climate presets 和 fan modes。无法为其他 state attributes 提供 icons。以下示例为 climate entity 提供 icons，其 translation_key 属性设为 ubercool。该 entity 有一个 preset_mode state attribute，可以设为 vacation 或 night。前端将在例如 climate card 中使用它们。

请注意，translated state attributes 必须像所有其他 translation key 一样是 snake_case。

{
  "entity": {
    "climate": {
      "ubercool": {
        "state_attributes": {
          "preset_mode": {
            "default": "mdi:confused",
            "state": {
              "vacation": "mdi:umbrella-beach",
              "night": "mdi:weather-night"
            }
          }
        }
      }
    }
  }
}

#图标属性

为 entity 提供 icon 的另一种方法是设置 entity 的 icon 属性，该属性返回一个引用 mdi icon 的字符串。由于该属性是一个 method，与 icon translations 不同，它可以根据自定义逻辑返回不同的 icons。例如，可以像下面示例中那样根据 state 计算 icon，或者根据不属于 entity state 的内容返回不同的 icons。

class MySwitch(SwitchEntity):

    @property
    def icon(self) -> str | None:
        """Icon of the entity, based on time."""
        if now().hour < 12:
            return "mdi:weather-night"
        return "mdi:weather-sunny"

    ...

无法通过 icon 属性为 state attributes 提供 icons。请注意，不建议使用 icon 属性；优先使用上述的 icon translations。

#从 recorder history 中排除状态属性

不适合进行 state history 记录的 state attributes 应通过将其包含在 _entity_component_unrecorded_attributes 或 _unrecorded_attributes 中来排除在 state history 记录之外。

• _entity_component_unrecorded_attributes: frozenset[str] 可在 base component 类中设置，例如在 light.LightEntity 中
• _unrecorded_attributes: frozenset[str] 可在集成的 platform 中设置，例如在 platform hue.light 中定义的 entity 类中。

MATCH_ALL 常量可用于排除所有 attributes，而无需逐一列出。对于提供未知 attributes 的集成，或者只是想排除所有而不逐一列出时，这非常有用。

使用 MATCH_ALL 常量不会停止对 device_class、state_class、unit_of_measurement 和 friendly_name 的记录，因为它们还可能服务于其他目的，因此不应排除在记录之外。

被排除在记录之外的 platform state attributes 示例包括 image entity 的 entity_picture attribute（一段时间后将会失效）和 fan entity 的 preset_modes attribute（不太可能变化）。 被排除在记录之外的集成特定 state attributes 示例包括 platform trafikverket.camera 中的 description 和 location state attributes（不会变化）。

#更改 entity model

如果你想为 entity 或其任何 subtype（light、switch 等）添加新 feature，你需要先在我们的 architecture repo 中提出。只考虑各种厂商通用的 features。