数字组件

ESPHome 支持创建数字实体的组件。数字实体类似于可以从设备读取值的传感器，但当该值可以由用户/前端设置时非常有用。

NOTE

ESPHome 数字实体需要 Home Assistant Core 2021.7 或更高版本才能正常工作。

基本数字配置

ESPHome 中的所有数字都有一个名称和可选的图标。

# 示例数字配置
name: 客厅音量

# 可选变量：
icon: "mdi:volume-high"

配置变量：

id (可选, string)：手动指定用于代码生成的 ID。必须指定 id 和 name 中的至少一个。
name (可选, string)：数字的名称。必须指定 id 和 name 中的至少一个。

NOTE

如果您为设备设置了 friendly_name，并且希望数字使用该名称，可以设置 name: None。

icon (可选, icon)：手动设置前端中数字使用的图标。
internal (可选, boolean)：将此组件标记为内部组件。内部组件不会暴露给前端（如 Home Assistant）。仅指定 id 而不指定 name 会隐式将此设置为 true。
disabled_by_default (可选, boolean)：如果为 true，则此实体不应添加到任何客户端的前端（通常是 Home Assistant），除非用户手动启用（通过 Home Assistant UI）。默认为 false。
entity_category (可选, string)：实体的类别。请参阅 https://developers.home-assistant.io/docs/core/entity/#generic-properties 获取可用选项列表。设置为 "" 可移除默认实体类别。
unit_of_measurement (可选, string)：手动设置数字的计量单位。
mode (可选, string)：定义数字在前端中的显示方式。请参阅 https://developers.home-assistant.io/docs/core/entity/number/#properties 获取可用选项列表。默认为 "auto"。
device_class (可选, string)：数字的设备类别。请参阅 https://www.home-assistant.io/integrations/number/#device-class 获取可用选项列表。
如果启用了 Webserver 并选择了版本 3，则支持 Webserver 组件的所有其他选项。请参阅 Webserver 版本 3。

自动化：

on_value (可选, 自动化)：当发布新值时要执行的自动化。请参阅 on_value。
on_value_range (可选, 自动化)：当发布的值从范围外转换到范围内时要执行的自动化。请参阅 on_value_range。

MQTT 选项：

MQTT 组件的所有其他选项。

数字自动化

您可以在 lambda 中使用 id(number_id).state 访问数字的最新状态。

`on_value`

当发布新值时将触发此自动化。在 Lambda 中，您可以从触发器中使用 x 获取该值。

number:
  - platform: template
    # ...
    on_value:
      then:
        - light.turn_on:
            id: light_1
            red: !lambda "return x/255;"

配置变量：请参阅自动化。

`on_value_range`

使用此自动化，您可以观察数字值是否从定义的范围外传递到范围内。此触发器仅在新值在范围内且之前的值在范围外时触发。启动时，会恢复重启前的最后状态，如果在启动过程中值跨越了边界，也会执行触发器。

使用 above 和 below 定义范围。如果只定义了其中一个，则区间为半开区间。例如，above: 5 且没有 below 将表示从 5 到正无穷大的范围。

number:
  - platform: template
    # ...
    on_value_range:
      above: 5
      below: 10
      then:
        - switch.turn_on: relay_1

配置变量：

above (可选, float)：触发器的最小值。
below (可选, float)：触发器的最大值。
请参阅自动化。

`number.in_range` 条件

如果给定数字的状态在范围内，则此条件通过。

使用 above 和 below 定义范围。如果只定义了其中一个，则区间为半开区间。例如，above: 5 且没有 below 将表示从 5 到正无穷大的范围。

# 在触发器中：
on_...:
  if:
    condition:
      number.in_range:
        id: my_number
        above: 50.0
    then:
      - script.execute: my_script

配置变量：

above (可选, float)：条件的最小值。
below (可选, float)：条件的最大值。

`number.set` 动作

这是一个用于设置数字状态的动作。

- number.set:
    id: my_number
    value: 42

配置变量：

id (必填, ID)：要设置的数字的 ID。
value (必填, float, 可模板化)：要将数字设置为的值。

`number.increment` 动作

这是一个用于按步长（默认：1）递增数字值的动作。

- number.increment:
    id: my_number
    cycle: false

# 简写形式
- number.increment: my_number

配置变量：

id (必填, ID)：要更新的数字组件的 ID。
cycle (可选, boolean)：当递增使值超过最大值时，是否将数字设置为其最小值。这仅在数字组件使用最小值和最大值时有效。默认为 true。

`number.decrement` 动作

这是一个用于按步长（默认：1）递减数字值的动作。

- number.decrement:
    id: my_number
    cycle: false

# 简写形式
- number.decrement: my_number

配置变量：

id (必填, ID)：要更新的数字组件的 ID。
cycle (可选, boolean)：当递减使值低于最小值时，是否将数字设置为其最大值。这仅在数字组件使用最小值和最大值时有效。默认为 true。

`number.to_min` 动作

这是一个将数字设置为其最小值的动作，前提是为数字组件定义了最小值。

- number.to_min:
    id: my_number

# 简写形式
- number.to_min: my_number

配置变量：

id (必填, ID)：要更新的数字组件的 ID。

`number.to_max` 动作

这是一个将数字设置为其最大值的动作，前提是为数字组件定义了最大值。

- number.to_max:
    id: my_number

# 简写形式
- number.to_max: my_number

配置变量：

id (必填, ID)：要更新的数字组件的 ID。

`number.operation` 动作

这是一个可以对数字组件执行操作（设置为最小值或最大值、递减、递增）的动作，使用通用的可模板化动作调用。

# 使用值
- number.operation:
    id: my_number
    operation: Increment
    cycle: true

# 或使用模板（lambda）
- number.operation:
    id: my_number
    operation: !lambda "return NUMBER_OP_INCREMENT;"
    cycle: !lambda "return true;"

配置变量：

id (必填, ID)：要更新的数字的 ID。
operation (必填, string, 可模板化)：要对数字组件执行的操作。可选值为 TO_MIN、TO_MAX、DECREMENT 或 INCREMENT（不区分大小写）。为此字段编写 lambda 时，返回以下枚举值之一：NUMBER_OP_TO_MIN、NUMBER_OP_TO_MAX、NUMBER_OP_DECREMENT 或 NUMBER_OP_INCREMENT。
cycle (可选, bool, 可模板化)：可与 DECREMENT 或 INCREMENT 一起使用，以指定当分别超过数字的最小值或最大值时是否循环回绕。

lambda 调用

在 lambda 中，您可以对所有数字调用多种方法来执行一些高级操作（有关更多信息，请参阅完整的 API 参考）。

.make_call()：创建用于更新数字值的调用。

    // 在 lambda 中，推送值 42
    auto call = id(my_number).make_call();
    call.set_value(42);
    call.perform();

请查看 API 参考，了解 NumberCall 对象可用的方法。例如，您也可以使用 call.number_to_min() 将数字设置为其最小值，或使用 call.number_increment(true) 在启用循环功能的情况下按步长递增数字。

.state：检索数字的当前值。如果尚未读取或设置值，则为 NAN。

    // 例如，在接收到值时创建自定义日志消息：
    ESP_LOGI("main", "我的数字值：%f", id(my_number).state);

数字组件

基本数字配置

数字自动化

on_value

on_value_range

number.in_range 条件

number.set 动作

number.increment 动作

number.decrement 动作

number.to_min 动作

number.to_max 动作

number.operation 动作

lambda 调用

另请参阅

`on_value`

`on_value_range`

`number.in_range` 条件

`number.set` 动作

`number.increment` 动作

`number.decrement` 动作

`number.to_min` 动作

`number.to_max` 动作

`number.operation` 动作