文本组件

ESPHome 支持创建文本实体的组件。文本实体类似于可以从设备读取值的 text_sensor，但当该值可以由用户/前端设置时非常有用。

NOTE

ESPHome 文本实体需要 Home Assistant Core 2023.11 或更高版本才能正常工作。

基本文本配置

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

# 示例文本配置
name: 客厅文本

# 可选变量：
icon: "mdi:cursor-text"

配置变量：

• id (可选, string)：手动指定用于代码生成的 ID。必须指定 id 和 name 中的至少一个。
• name (必填, string)：文本的名称。

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 获取可用选项列表。设置为 "" 可移除默认实体类别。

• mode (必填, string)：定义文本在前端中的显示方式。可选 text 或 password。

• 如果启用了 Webserver 并选择了版本 3，则支持 Webserver 组件的所有其他选项。请参阅 Webserver 版本 3。

自动化：

• on_value (可选, 自动化)：当发布新值时要执行的自动化。请参阅 on_value。

MQTT 选项：

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

文本自动化

您可以在 lambda 中使用 id(text_id).state 访问文本的最新状态。

on_value

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

text:
  - platform: template
    # ...
    on_value:
      then:
        - logger.log:
            format: "%s"
            args: ["x.c_str()"]

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

text.set 动作

这是一个用于设置文本状态的 动作。

- text.set:
    id: my_text
    value: "Hello World"

配置变量：

• id (必填, ID)：要设置的文本的 ID。
• value (必填, string, 可模板化)：要将文本设置为的值。

lambda 调用

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

• .make_call()：创建用于更新文本值的调用。

    // 在 lambda 中，推送值 42
    auto call = id(my_text).make_call();
    call.set_value("Hello World");
    call.perform();

• .state：检索文本的当前值。

    // 例如，在接收到值时创建自定义日志消息：
    ESP_LOGI("main", "我的文本值：%s", id(my_text).state.c_str());

另请参阅

• API Reference: Text
• API Reference: TextCall