Number Component

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

NOTE

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

基础数字配置

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

# 示例数字配置
name: Livingroom Volume

# 可选变量：
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（可选，Automation）：发布新值时执行的自动化。参见 on_value。
on_value_range（可选，Automation）：当发布值从范围外部转换到范围内部时执行的自动化。参见 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 到正无穷的范围。

# in a trigger:
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，templatable）：要设置的数字值。

`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，templatable）：要对数字组件执行的操作。可选 TO_MIN、TO_MAX、DECREMENT 或 INCREMENT（不区分大小写）。为此字段编写 lambda 时，请返回以下枚举值之一：NUMBER_OP_TO_MIN、NUMBER_OP_TO_MAX、NUMBER_OP_DECREMENT 或 NUMBER_OP_INCREMENT。
cycle（可选，bool，templatable）：可与 DECREMENT 或 INCREMENT 配合使用，以指定当分别超过数字的最小值或最大值时是否环绕值。

lambda 调用

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

.make_call()：为更新数字值发起调用。

    // Within lambda, push a value of 42
    auto call = id(my_number).make_call();
    call.set_value(42);
    call.perform();

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

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

    // 例如，在收到值时创建自定义日志消息：
    ESP_LOGI("main", "Value of my number: %f", id(my_number).state);

Number Component

基础数字配置

数字自动化

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` 操作