Text Sensor 组件

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

基础 Text Sensor 配置

# 示例传感器配置
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 Component 的所有其他选项。
如果启用了 Webserver 并选择了版本 3，则包含 Webserver 组件的所有其他选项。参见 Webserver 版本 3。

自动化：

on_value（可选，Automation）：发布新值时要执行的自动化。参见 on_value。
on_raw_value（可选，Automation）：收到未通过任何过滤器的新值时要执行的自动化。参见 on_raw_value。

Text Sensor 过滤器

ESPHome 允许你在将 text_sensor 值发送到 Home Assistant 之前对其进行一些基本预处理。这在你想要以某种方式操作 text_sensor 字符串时很有用。

传感器支持大量过滤器。通过在 text_sensor 配置中添加 filters 块来定义它们（与 platform 同级；或者在包含多个传感器的平台的每个 text_sensor 块内）。

过滤器按配置中定义的顺序处理。

# 示例过滤器：
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"

参数是一个替换列表，每个替换的形式为 TO_FIND -> REPLACEMENT。

`map`

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

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

参数是一个替换列表，每个替换的形式为 LOOKUP -> REPLACEMENT。

`lambda`

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

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

Text Sensor 自动化

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

`on_value`

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

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

配置变量：参见 Automation。

`on_raw_value`

收到未通过任何过滤器的新值时将触发此自动化。在 Lambdas 中可以通过 x 从触发器获取值。

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

配置变量：参见 Automation。

`text_sensor.state` 条件

此 Condition 允许你检查给定文本传感器是否具有特定状态。

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

配置变量：

id（必选，ID）：文本传感器 ID。
state（必选，string，templatable）：要与之比较的状态。

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 参考：text_sensor.h

Text Sensor 组件

基础 Text Sensor 配置

Text Sensor 过滤器

to_upper

to_lower

append

prepend

substitute

map

lambda