文本传感器组件

文本传感器与普通传感器非常相似。但普通传感器只能表示输出数字的传感器，而此组件可以表示任何文本。

文本传感器基本配置

# 示例传感器配置
name: Livingroom Temperature

# 可选变量：
icon: "mdi:water-percent"

配置变量：

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

NOTE

如果您的设备设置了 friendly_name，并且您希望文本传感器使用该名称，可以设置 name: None。

icon (可选, icon): 手动设置前端显示的传感器图标。
device_class (可选, string): 传感器的设备类别。仅支持 timestamp 和 date 设备类别。设置为 "" 可移除传感器的默认设备类别。需要 Home Assistant 2024.3 或更高版本。
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 获取可用选项列表。设置为 "" 可移除默认的实体类别。
如果启用了 MQTT，则支持 MQTT 组件的所有其他选项。
如果启用了 Webserver 并选择了版本 3，则支持 Webserver 组件的所有其他选项。请参阅 Webserver 版本 3。

自动化：

on_value (可选, 自动化): 当发布新值时执行的自动化。请参阅 on_value。
on_raw_value (可选, 自动化): 当收到尚未经过任何过滤器处理的新值时执行的自动化。请参阅 on_raw_value。

文本传感器过滤器

ESPHome 允许您在文本传感器值发送到 Home Assistant 之前对其进行一些基本预处理。例如，如果您想以某种方式操作文本传感器字符串，这会很有用。

传感器支持许多过滤器。您可以通过在文本传感器配置中添加 filters 块来定义它们（与 platform 同级；对于有多个传感器的平台，则在每个文本传感器块内部）。

过滤器按照它们在配置中定义的顺序进行处理。

# 示例过滤器：
filters:
  - to_upper:
  - to_lower:
  - append: "_suffix"
  - prepend: "prefix_"
  - substitute:
    - "suf -> foo"
    - "pre -> bar"
  - lambda: return {"Hello World"};

`to_upper`

将字符串中的所有字符转换为大写（目前仅支持英文字母）。

# 示例配置条目
- platform: template
  # ...
  filters:
    - to_upper:

`to_lower`

将字符串中的所有字符转换为小写（目前仅支持英文字母）。

# 示例配置条目
- platform: template
  # ...
  filters:
    - to_lower:

`append`

在当前字符串末尾添加一个字符串。

# 示例配置条目
- platform: template
  # ...
  filters:
    - append: "_suffix"

`prepend`

在当前字符串开头添加一个字符串。

# 示例配置条目
- platform: template
  # ...
  filters:
    - prepend: "prefix_"

`substitute`

在文本传感器的当前值中搜索一个字符串，并将其替换为另一个字符串。

# 示例配置条目
- platform: template
  # ...
  filters:
    - substitute:
      - "suf -> foo"
      - "pre -> bar"

参数是一个替换列表，每项格式为 要查找的内容 -> 替换内容。

`map`

在列表中查找文本传感器的当前值，如果找到则返回匹配项。如果未找到当前值，则不更改文本传感器的值。

# 示例配置条目
- platform: template
  # ...
  filters:
    - map:
      - high -> On
      - low -> Off

参数是一个映射列表，每项格式为 查找值 -> 替换值。

`lambda`

对文本传感器值执行高级操作。输入字符串为 x， lambda 的结果用作输出（使用 return）。

filters:
  - lambda: |-
      if (x == "Hello") {
        return x + "bar";
      } else {
        return x + "foo";
      }

文本传感器自动化

您可以在 lambda 中使用 id(sensor_id).state 访问传感器的最新状态。

`on_value`

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

text_sensor:
  - platform: version
    # ...
    on_value:
      then:
        - lambda: |-
            ESP_LOGD("main", "The current version is %s", x.c_str());

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

`on_raw_value`

当收到尚未经过任何过滤器处理的新值时将触发此自动化。在 Lambda 中，您可以通过 x 从触发器获取值。

text_sensor:
  - platform: version
    # ...
    on_raw_value:
      then:
        - lambda: |-
            ESP_LOGD("main", "The current version is %s", x.c_str());

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

`text_sensor.state` 条件

此条件允许您检查给定的文本传感器是否具有特定状态。

on_...:
  - if:
      condition:
        # 检查 "my_text_sensor" 是否具有状态 "Hello World"
        text_sensor.state:
          id: my_text_sensor
          state: 'Hello World'

配置变量：

id (必需, ID): 文本传感器 ID。
state (必需, 可模板化, string): 要比较的状态。

NOTE

此条件也可以用 lambda 表达：

if (id(my_text_sensor).state == "Hello World") {
  // 执行某些操作
}

lambda 调用

从 lambda 中，您可以在所有文本传感器上调用多个方法来执行一些高级操作（更多信息请参阅完整的 API 参考）。

publish_state(): 手动使传感器推送出一个值。

    // 在 lambda 中，推送一个值 "Hello World"
    id(my_sensor).publish_state("Hello World");

.state: 以 std::string 对象形式检索传感器的当前值。

    // 例如，在收到值时创建自定义日志消息：
    std::string val = id(my_sensor).state;
    ESP_LOGI("main", "Value of my sensor: %s", val.c_str());

另请参阅

API Reference: text_sensor.h

文本传感器组件

文本传感器基本配置

文本传感器过滤器

to_upper

to_lower

append

prepend

substitute

map

lambda