选择器组件

ESPHome 支持创建选择器实体的组件。选择器实体基本上是一个可以由 yaml、硬件或用户/前端设置的选项列表。

NOTE

ESPHome 选择器实体需要 Home Assistant Core 2021.8 或更高版本才能正常工作。

基本选择器配置

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

# 示例选择器配置
name: 客厅氛围
id: my_select

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

配置变量：

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 获取可用选项列表。设置为 "" 可移除默认实体类别。
如果启用了 Webserver 并选择了版本 3，则支持 Webserver 组件的所有其他选项。请参阅 Webserver 版本 3。
on_value (可选, 自动化)：当发布新值时要执行的自动化。请参阅 on_value。

MQTT 选项：

MQTT 组件的所有其他选项。

访问当前选项

您可以在 lambda 中使用 id(select_id).current_option() 访问选择器的最新状态。有关在选择器中使用 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` 条件

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

配置变量：

id (必填, ID)：要测试的选择器的 ID。
options (可选, list)：要与当前选择进行比较的字符串或字符串列表。如果任一匹配，则条件为 true。
lambda (可选, 可模板化)：返回布尔值的 lambda。当前选择在名为 current 的 StringRef 参数中传递。

只能提供 options 和 lambda 中的一个。

# 在某个触发器中：
on_...:
  - if:
      condition:
        select.is:
          id: my_select
          options: [开心, 兴奋]
      then:
        - logger.log: "选择器是开心或兴奋"
  - if:
      condition:
        select.is:
          id: my_select
          options: "开心" # 单个选项
      then:
        - logger.log: "选择器正好是开心"
  - if:
      condition:
        select.is:
          id: my_select
          lambda: return id(text_sensor).state == current || "开心" == current;
      then:
        - logger.log: "选择器是开心，或匹配某个变量状态"

动作

`select.set` 动作

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

- select.set:
    id: my_select
    option: "开心"

配置变量：

id (必填, ID)：要设置的选择器的 ID。
option (必填, string, 可模板化)：要将选择器设置为的选项。

当使用不存在的选项值时，会记录警告，选择器的状态保持不变。

`select.set_index` 动作

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

- select.set_index:
    id: my_select
    index: 3

配置变量：

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

当使用不存在的索引值时，会记录警告，选择器的状态保持不变。

`select.next` 动作

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

- select.next:
    id: my_select
    cycle: false

# 简写形式
- select.next: my_select

配置变量：

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

`select.previous` 动作

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

- select.previous:
    id: my_select
    cycle: true

# 简写形式
- select.previous: my_select

配置变量：

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

`select.first` 动作

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

- select.first:
    id: my_select

# 简写形式
- select.first: my_select

配置变量：

id (必填, ID)：要设置的选择器的 ID。

`select.last` 动作

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

- select.last:
    id: my_select

# 简写形式
- select.last: my_select

配置变量：

id (必填, ID)：要设置的选择器的 ID。

`select.operation` 动作

这是一个可以使用通用的可模板化动作调用来更改选择器组件中活动选项（第一个、最后一个、上一个或下一个）的动作。

# 使用值
- 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)：要设置的选择器的 ID。
operation (必填, string, 可模板化)：要执行的操作。可选值为 FIRST、LAST、PREVIOUS 或 NEXT（不区分大小写）。为此字段编写 lambda 时，返回以下枚举值之一：SELECT_OP_FIRST、SELECT_OP_LAST、SELECT_OP_PREVIOUS 或 SELECT_OP_NEXT。
cycle (可选, bool, 可模板化)：可用于 NEXT 和 PREVIOUS 选项，以指定当分别激活选择器中最后一个或第一个选项时是否循环回绕选项列表。

在 Lambda 中使用选择器

在 lambda 中，您可以调用选择器的多种方法（有关更多信息，请参阅完整的 API 参考）。

.make_call()：创建用于更改选择器状态的调用。

    // 在 lambda 中，选择"开心"选项。
    auto call = id(my_select).make_call();
    call.set_option("开心");
    call.perform();

请查看 API 参考，了解 SelectCall 对象可用的方法。例如，您也可以使用 call.select_first() 选择第一个选项，或使用 call.select_next(true) 在启用循环功能的情况下选择下一个选项。

.current_option()：检索选择器当前选择的选项。返回 StringRef。

    // 例如，在选择选项时创建自定义日志消息：
    auto option = id(my_select).current_option();
    ESP_LOGI("main", "我的选择器选项：%.*s", (int) option.size(), option.c_str());

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

.size()：检索选择器中选项的数量。

    auto size = id(my_select).size();
    ESP_LOGI("main", "选择器有 %d 个选项", size);

.index_of(<option value>)：检索选项值的索引偏移量。

    auto index = id(my_select).index_of("开心");
    if (index.has_value()) {
      ESP_LOGI("main", "'开心' 在索引：%d", index.value());
    } else {
      ESP_LOGE("main", "没有选项'开心'");
    }

.active_index()：检索当前活动选项的索引。

    auto index = id(my_select).active_index();
    if (index.has_value()) {
      ESP_LOGI("main", "索引 %d 处的选项是活动的", index.value());
    } else {
      ESP_LOGI("main", "没有活动选项");
    }

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

    auto index = 1;
    auto option = id(my_select).at(index);
    if (option.has_value()) {
      auto value = option.value();
      ESP_LOGI("main", "%d 处的选项是：%s", index, value);
    } else {
      ESP_LOGE("main", "索引 %d 不存在", index);
    }

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

    auto option = "开心";
    if (id(my_select).has_option(option)) {
      ESP_LOGI("main", "选择器有选项'%s'", option);
    }

.has_index(<index offset>)：检查选择器是否包含给定索引偏移量的选项值。

    auto index = 3;
    if (id(my_select).has_index(index)) {
      ESP_LOGI("main", "选择器有索引偏移量 %d", index);
    }

示例

设置三个选项并将组件状态设置为所选选项值。

select:
  - platform: template
    name: 模式
    id: mode
    options:
     - "选项1"
     - "选项2"
     - "选项3"
    initial_option: "选项1"
    optimistic: true
    set_action:
      - logger.log:
          format: "选择的选项：%s"
          args: ["x.c_str()"]

选择器组件

基本选择器配置

访问当前选项

触发器

on_value

条件

select.is 条件

动作

select.set 动作

select.set_index 动作

select.next 动作

select.previous 动作

select.first 动作

select.last 动作

select.operation 动作

在 Lambda 中使用选择器

示例

另请参阅

`on_value`

`select.is` 条件

`select.set` 动作

`select.set_index` 动作

`select.next` 动作

`select.previous` 动作

`select.first` 动作

`select.last` 动作

`select.operation` 动作