mirror of
https://github.com/home-assistant/developers.home-assistant.git
synced 2025-07-22 16:56:29 +00:00
Document NumberEntity refactoring (#1367)
* Document NumberEntity refactoring * Update docs/core/entity/number.md Co-authored-by: Martin Hjelmare <marhje52@gmail.com> Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
This commit is contained in:
parent
17742eaf49
commit
468b661883
26
blog/2022-06-14-number_entity_refactoring.md
Normal file
26
blog/2022-06-14-number_entity_refactoring.md
Normal file
@ -0,0 +1,26 @@
|
||||
---
|
||||
author: Erik Montnemery
|
||||
authorURL: https://github.com/emontnemery
|
||||
title: "Number entity refactoring to support unit conversion"
|
||||
---
|
||||
|
||||
`NumberEntity` now supports temperature unit conversion following a similar pattern
|
||||
as the unit conversion supported by `SensorEntity`.
|
||||
|
||||
Temperature conversion will automatically be done for number entities with device
|
||||
class set to `temperature` to the temperature unit configured by the user.
|
||||
|
||||
To make this possible, custom component integrations should be updated to override
|
||||
properties `native_max_value`, `native_min_value`, `native_step`,
|
||||
`native_unit_of_measurement`, `native_value` instead of `max_value`, `min_value`,
|
||||
`step`, `unit_of_measurement`, `value` and to override methods `async_set_native_value`
|
||||
and `set_native_value` instead of `async_set_value` and `set_value`.
|
||||
|
||||
The same renaming has been done for `_attr_*` attributes as well as members of
|
||||
`NumberEntityDescription`.
|
||||
|
||||
In Home Assistant Core 2023.1, overriding `async_set_value`, `max_value`, `min_value`,
|
||||
`set_value`, `step`, `unit_of_measurement`, `value`, setting `_attr_max_value`,
|
||||
`_attr_min_value`, `_attr_unit_of_measurement`, `_attr_step`, `_attr_value` and
|
||||
setting `max_value`, `min_value`, `unit_of_measurement`, `step` on instances of
|
||||
`NumberEntityDescription` is no longer supported.
|
@ -13,30 +13,40 @@ Properties should always only return information from memory and not do I/O (lik
|
||||
|
||||
| Name | Type | Default | Description
|
||||
| ---- | ---- | ------- | -----------
|
||||
| value | float | **Required** | Current value of the entity
|
||||
| min_value | float | 0 | The minimum accepted value (inclusive)
|
||||
| max_value | float | 100 | The maximum accepted value (inclusive)
|
||||
| step | float | **See below** | Defines the resolution of the values, i.e. the smallest increment or decrement
|
||||
| device_class | string | `None` | Type of number.
|
||||
| mode | string | `auto` | Defines how the number should be displayed in the UI. It's recommended to use the default `auto`. Can be `box` or `slider` to force a display mode.
|
||||
| native_max_value | float | 100 | The maximum accepted value in the number's `native_unit_of_measurement` (inclusive)
|
||||
| native_min_value | float | 0 | The minimum accepted value in the number's `native_unit_of_measurement` (inclusive)
|
||||
| native_step | float | **See below** | Defines the resolution of the values, i.e. the smallest increment or decrement in the number's | native_unit_of_measurement | string | `None` | The unit of measurement that the number's value is expressed in. If the `native_unit_of_measurement` is °C or °F, and its `device_class` is temperature, the number's `unit_of_measurement` will be the preferred temperature unit configured by the user and the number's `state` will be the `native_value` after an optional unit conversion.
|
||||
| native_value | float | **Required** | The value of the number in the number's `native_unit_of_measurement`.
|
||||
`native_unit_of_measurement`
|
||||
|
||||
Other properties that are common to all entities such as `icon`, `unit_of_measurement`, `name` etc are also applicable.
|
||||
Other properties that are common to all entities such as `icon`, `name` etc are also applicable.
|
||||
|
||||
The default step value is dynamically chosen based on the range (max - min) values. If the difference between max_value and min_value is greater than 1.0, then the default step is 1.0. If, however, the range is smaller, then the step is iteratively divided by 10 until it becomes lower than the range.
|
||||
|
||||
### Available device classes
|
||||
|
||||
If specifying a device class, your number entity will need to also return the correct unit of measurement.
|
||||
|
||||
| Type | Supported units | Description
|
||||
| ---- | ---- | -----------
|
||||
| temperature | °C, °F | Temperature.
|
||||
|
||||
## Methods
|
||||
|
||||
### Set value
|
||||
|
||||
Called when the user or automation wants to update the value.
|
||||
Called when the user or an automation wants to update the value.
|
||||
|
||||
```python
|
||||
class MyNumber(NumberEntity):
|
||||
# Implement one of these methods.
|
||||
|
||||
def set_value(self, value: float) -> None:
|
||||
def set_native_value(self, value: float) -> None:
|
||||
"""Update the current value."""
|
||||
|
||||
async def async_set_value(self, value: float) -> None:
|
||||
async def async_set_native_value(self, value: float) -> None:
|
||||
"""Update the current value."""
|
||||
|
||||
```
|
||||
|
Loading…
x
Reference in New Issue
Block a user