Select 组件

ESPHome 支持用于创建 select 实体的组件。select 实体本质上是一个选项列表，可以通过 YAML、硬件或用户/前端来设置。

NOTE

需要 Home Assistant Core 2021.8 或更高版本才能使 ESPHome 的 select 实体正常工作。

基础 Select 配置

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

# 示例 select 配置
name: Livingroom Mood
id: my_select

# 可选变量：
icon: "mdi:emoticon-outline"

配置变量：

id (可选, string): 手动指定用于代码生成的 ID。必须至少指定 id 和 name 之一。
name (可选, string): select 的名称。必须至少指定 id 和 name 之一。

NOTE

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

icon (可选, icon): 手动设置前端中 select 使用的图标。
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 获取可用选项列表。设置为 "" 以移除默认的实体类别。
如果启用了 Web 服务器且选择了版本 3，则还包括 Web 服务器组件的所有其他选项。参见 Web 服务器版本 3。
on_value (可选, 自动化): 在发布新值时要执行的自动化。参见 on_value。

MQTT 选项：

MQTT 组件中的所有其他选项。

访问当前选项

您可以在 lambda 中使用 id(select_id).current_option() 访问 select 的最新状态。有关在 select 中使用 lambda 的更多信息，请参阅 lambda 调用。

触发器

`on_value`

每当设置/发布值时，此自动化都会触发，即使值与之前相同也是如此。在 Lambda 中，您可以通过 x 从触发器获取值，并通过 i 获取所选值的索引偏移量。

select:
  - platform: template
    # ...
    on_value:
      then:
        - logger.log:
            format: "所选选项: %s (索引 %d)"
            args: ["x.c_str()", "i"]

配置变量：参见自动化。

条件

`select.is` 条件

此条件检查 select 是否设置为选项列表中的任何一个。也可以使用 lambda 进行更复杂的计算。

配置变量：

id (必填, ID): 要测试的 select 的 ID。
options (可选, list): 一个字符串或字符串列表，用于与当前选择进行比较。如果有任一匹配，条件即为真。
lambda (可选, lambda): 返回布尔值的 lambda。当前选择通过名为 current 的 StringRef 参数传入。

options 和 lambda 必须只提供其中一个。

# 在某个触发器中：
on_...:
  - if:
      condition:
        select.is:
          id: my_select
          options: [Happy, Ecstatic]
      then:
        - logger.log: "Select 为 Happy 或 Ecstatic"
  - if:
      condition:
        select.is:
          id: my_select
          options: "Happy" # 单个选项
      then:
        - logger.log: "Select 恰好为 Happy"
  - if:
      condition:
        select.is:
          id: my_select
          lambda: return id(text_sensor).state == current || "Happy" == current;
      then:
        - logger.log: "Select 为 Happy，或匹配某个变量的状态"

动作

`select.set` 动作

这是一个用于使用选项值设置活动选项的动作。

- select.set:
    id: my_select
    option: "Happy"

配置变量：

id (必填, ID): 要设置的 select 的 ID。
option (必填, string, 可模板化): 要将 select 设置的选项。

当使用不存在的选项值时，会记录一条警告，并且 select 的状态保持原样。

`select.set_index` 动作

这是一个用于使用索引偏移量设置活动选项的动作。

- select.set_index:
    id: my_select
    index: 3

配置变量：

id (必填, ID): 要设置的 select 的 ID。
index (必填, int, 可模板化): 要激活选项的索引偏移量。

当使用不存在的索引值时，会记录一条警告，并且 select 的状态保持原样。

`select.next` 动作

这是一个用于在 select 组件中选择下一个选项的动作。

- select.next:
    id: my_select
    cycle: false

# 简写
- select.next: my_select

配置变量：

id (必填, ID): 要设置的 select 的 ID。
cycle (可选, boolean): 当当前选中最后一个选项时，是否跳回 select 的第一个选项。默认为 true。

`select.previous` 动作

这是一个用于在 select 组件中选择上一个选项的动作。

- select.previous:
    id: my_select
    cycle: true

# 简写
- select.previous: my_select

配置变量：

id (必填, ID): 要设置的 select 的 ID。
cycle (可选, boolean): 当当前选中第一个选项时，是否跳到 select 的最后一个选项。默认为 true。

`select.first` 动作

这是一个用于在 select 组件中选择第一个选项的动作。

- select.first:
    id: my_select

# 简写
- select.first: my_select

配置变量：

id (必填, ID): 要设置的 select 的 ID。

`select.last` 动作

这是一个用于在 select 组件中选择最后一个选项的动作。

- select.last:
    id: my_select

# 简写
- select.last: my_select

配置变量：

id (必填, ID): 要设置的 select 的 ID。

`select.operation` 动作

这是一个动作，可用于更改 select 组件中的活动选项（first、last、previous 或 next），使用通用的可模板化动作调用。

# 使用值
- select.operation:
    id: my_select
    operation: Next
    cycle: true

# 或使用模板（lambda）
- select.operation:
    id: my_select
    operation: !lambda "return SELECT_OP_NEXT;"
    cycle: !lambda "return true;"

配置变量：

id (必填, ID): 要设置的 select 的 ID。
operation (必填, string, 可模板化): 要执行的操作。可选值为 FIRST、LAST、PREVIOUS 或 NEXT（不区分大小写）。编写此字段的 lambda 时，请返回以下枚举值之一：SELECT_OP_FIRST、SELECT_OP_LAST、 SELECT_OP_PREVIOUS 或 SELECT_OP_NEXT。
cycle (可选, bool, 可模板化): 可用于 NEXT 和 PREVIOUS 选项，指定当 select 中最后或第一个选项当前活动时，是否环绕选项列表。

在 Lambda 中使用 Select

从 lambda 中，您可以对 select 调用几种方法（更多信息请参见完整的 API 参考）。

.make_call() : 创建一个用于更改 select 状态的调用。

    // 在 lambda 内部，选择 "Happy" 选项。
    auto call = id(my_select).make_call();
    call.set_option("Happy");
    call.perform();

查阅 API 参考以获取 SelectCall 对象的可用方法信息。例如，您也可以使用 call.select_first() 选择第一个选项，或使用 call.select_next(true) 选择启用环绕功能的下一个选项。

.current_option() : 获取 select 当前选中的选项。返回 StringRef。

    // 例如，当选择某个选项时创建自定义日志消息：
    auto option = id(my_select).current_option();
    ESP_LOGI("main", "Option of my select: %.*s", (int) option.size(), option.c_str());

    # 检查是否选中了特定选项（在 lambda 条件中进行直接字符串比较）
    - if:
        condition:
          - lambda: 'return id(my_select).current_option() == "my_option_value";'

.size() : 获取 select 中选项的数量。

    auto size = id(my_select).size();
    ESP_LOGI("main", "Select has %d options", size);

.index_of(<option value>) : 获取某个选项值的索引偏移量。

    auto index = id(my_select).index_of("Happy");
    if (index.has_value()) {
      ESP_LOGI("main", "'Happy' is at index: %d", index.value());
    } else {
      ESP_LOGE("main", "There is no option 'Happy'");
    }

.active_index() : 获取当前活动选项的索引。

    auto index = id(my_select).active_index();
    if (index.has_value()) {
      ESP_LOGI("main", "Option at index %d is active", index.value());
    } else {
      ESP_LOGI("main", "No option is active");
    }

.at(<index offset>) : 获取给定索引偏移量处的选项值。

    auto index = 1;
    auto option = id(my_select).at(index);
    if (option.has_value()) {
      auto value = option.value();
      ESP_LOGI("main", "Option at %d is: %s", index, value);
    } else {
      ESP_LOGE("main", "Index %d does not exist", index);
    }

.has_option(<option value>) : 检查 select 是否包含给定的选项值。

    auto option = "Happy";
    if (id(my_select).has_option(option)) {
      ESP_LOGI("main", "Select has option '%s'", option);
    }

.has_index(<index offset>) : 检查 select 是否包含给定索引偏移量对应的选项值。

    auto index = 3;
    if (id(my_select).has_index(index)) {
      ESP_LOGI("main", "Select has index offset %d", index);
    }

Select 组件

基础 Select 配置

访问当前选项

触发器

on_value

条件

select.is 条件

动作

select.set 动作

select.set_index 动作

select.next 动作

select.previous 动作

select.first 动作

select.last 动作

select.operation 动作

在 Lambda 中使用 Select

另请参阅

`on_value`

`select.is` 条件

`select.set` 动作

`select.set_index` 动作

`select.next` 动作

`select.previous` 动作

`select.first` 动作

`select.last` 动作

`select.operation` 动作