Home Assistant text.set_value 服务详解:用自动化设置文本实体的值

原创2026-09-16 12:39:022,194 阅读
文章标签:文档教程智能家居

Home Assistant text.set_value 服务详解:用自动化设置文本实体的值

text.set_value 是 Home Assistant 中用于设置文本(text)实体值的核心动作(action)——无论是显示屏上的留言、灯牌标签,还是任何设备向外暴露的可写文本,都可以通过它一次性写入指定内容。读完本文,你将掌握通过 UI 和 YAML 两种方式调用该服务的完整步骤、value 参数的取值约束(模式匹配与长度限制)、target 支持的实体/设备/区域等目标类型,以及一个「家人到家时自动显示欢迎语」的可直接复制的自动化示例,并了解它与 input_text.set_value 等相近服务的区别。

动作概览

text.set_value 的作用一句话概括:将某个 text 实体设置为特定值,例如一条标签、一段留言,或任何设备暴露出来的可写文本(来源文档:text.set_value 动作页)。

它的 front matter 元数据明确了服务归属:

title: "Set text value"
action: text.set_value
domain: text
description: "Sets the value of a text entity."

也就是说,该服务属于 text 域,只能作用于 text 实体。这一限定在「注意事项」部分会再次展开。

通过用户界面使用(UI)

如果你偏好可视化方式搭建自动化和脚本,Home Assistant 会逐步引导你完成这个动作:选择目标、调整几个选项、保存即可,全程不需要写 YAML。

操作步骤如下(对应 原文档的 UI 小节):

  1. 打开「设置」>「自动化与场景」(Settings > Automations & scenes)。
  2. 打开一个已有的自动化或脚本,或者选择 Create automation > Create new automation 新建。
  3. 如果是新建自动化,先在 When(触发条件)部分添加一个触发器。脚本则不需要触发器——脚本是被动执行的,由其他东西调用它时才运行。
  4. 在 Then do(执行动作)部分,选择 Add action。
  5. 选择你要控制的对象。在 By target(按目标,见下文 目标类型 一节)下选择要设置的那个 text 实体。
  6. 在该目标可用的动作列表中,选择 Set text value。
  7. 设置要应用的 Value(值)。
  8. 选择 Save 保存。

UI 表单中唯一的选项字段是 Value,其含义与约束如下:

选项 说明
Value 要设置到实体上的文本。它必须匹配实体允许的 pattern(模式),并且长度须落在实体的最小/最大长度范围内。

通过 YAML 使用

在 YAML 中,该服务写作 text.set_value。一个最基本的调用示例如下:

action:
  action: text.set_value
  target:
    entity_id: text.display_message
  data:
    value: "Welcome home"

这条调用会把 text.display_message 的值设置为 Welcome home。

YAML 参数说明

参数 是否必填 类型 说明
value 是 string 要设置到实体上的文本。必须匹配实体允许的 pattern,且长度须保持在实体的最小与最大长度之间。

value 是唯一的 data 字段,且为必填项。如果省略它,调用会因参数缺失而失败。

目标类型(Target)

该动作必须指定 target——target 是动作的作用对象。你可以把动作指向单个实体、设备、区域、楼层或标签,Home Assistant 会在该目标背后匹配到的每一个 text 实体上执行动作。支持的目标类型包括:

  • Entity(实体):某一个具体的 text 实体,例如 text.living_room。
  • Device(设备):属于某个设备的全部 text 实体。
  • Area(区域):某个房间/区域内的全部 text 实体。
  • Floor(楼层):某一层楼上的全部 text 实体。
  • Label(标签):共享同一个标签的全部 text 实体。

一个动作里还可以混合选择不同类型的目标。例如,你可以在同一个动作中同时添加一个具体实体和一个区域,动作会同时对它们生效。这在「给某个房间的显示屏写留言,同时给带某标签的灯牌也更新一遍」这类场景下很实用。

取值约束:pattern 与长度限制

原文档在「Good to know」中给出了两条关键约束,值得重点理解:

  1. 该动作只作用于 text 实体。指向 input_text、number 等其他域会不匹配。
  2. 值必须满足实体自身的约束:如果实体设置了 pattern(正则模式),value 必须能匹配;长度必须落在实体声明的最小/最大长度之间。超出这些限制的值会被直接拒绝,即写入不会生效。

从文档表述可以推断,这类校验是由实体/服务侧完成的:调用者不需要(也无法)绕过实体自身的 pattern 和长度规则。因此在编写自动化时,如果你的模板(value 支持模板渲染)可能产出超长或不符合模式的内容,应在模板层面先做截断与过滤,而不是依赖服务端的拒绝。

完整示例:有人到家时显示欢迎消息

这是一个把本动作放进自动化的真实场景:每当一位家人到家(person 实体状态变为 home),就把一个 text 实体设置为欢迎语,例如用来更新一块显示屏。

  • 触发器(Trigger):State: Person arrives home(人员到家状态触发)
  • 动作(Action):Set text value
    • Target:Display message
    • Value:Welcome home

完整 YAML 如下,可直接复制后按自己的实体名修改:

automation:
  - alias: "Show a welcome message"
    triggers:
      - trigger: state
        entity_id: person.your_name
        to: "home"
    actions:
      - action: text.set_value
        target:
          entity_id: text.display_message
        data:
          value: "Welcome home"

说明:

  • triggers 中使用 trigger: state,并限定 entity_id: person.your_name 与 to: "home",表示当该 person 实体进入 home 状态时触发。
  • actions 中的 text.set_value 即上文讲解的动作;target 指定具体的 text 实体,data.value 是要写入的文本。
  • 如果家里有多位成员,可以把 entity_id 写成多个 person 实体或改用区域/标签作为 target,让任意成员到家都触发欢迎语。

自己动手试试(Developer Tools)

想在不写 YAML 的情况下实测这个服务?打开「设置」>「工具」>「动作」(Settings > Tools > Actions),即开发者工具中的 Actions 页面,搜索 text.set_value,填入 entity_id 和 value 字段,点击 Perform action。你可以在不写一行 YAML 的情况下,直接在真实的 text 实体上看到写入效果。这也是排查「服务名写错」「实体不存在」一类问题的最快路径。

相关动作

与 text.set_value 配套或容易混淆的动作:

  • input_text.set_value:作用对象是 input_text 助手实体(Home Assistant 内部维护的文本助手),而不是设备暴露的 text 实体。如果你的目标实体是 input_text.xxx,应使用这个服务而不是 text.set_value。
  • input_text.reload:重新加载 input_text 助手配置,属于配置管理类动作。

判断用哪个服务的依据很简单:看目标实体的域——text.xxx 用 text.set_value,input_text.xxx 用 input_text.set_value。

常见问题的排查思路

结合原文档的约束条款,实际使用中「设置了但没生效」通常来自以下几点:

  1. 值不匹配 pattern:实体设置了正则约束,而你写入的文本(包括模板渲染结果)不符合该模式,写入被拒绝。检查实体的 pattern 设置,调整 value。
  2. 长度越界:写入的文本短于最小长度或长于最大长度,同样会被拒绝。可结合模板在写入前做长度控制。
  3. 目标域不对:把 text.set_value 用在了非 text 域的实体上。该动作只处理 text 实体,请确认 entity_id 的域前缀。
  4. 实体不存在或不可写:确认目标实体当前存在且由支持写入的集成提供;部分集成暴露的 text 实体可能仅可读。

如果仍然卡住,Home Assistant 社区通常响应很快:可以到社区 Discord、社区论坛或 /r/homeassistant 版块发帖提问,说明你调用的动作和预期现象;用自然语言描述需求后,AI 助手也可以帮你解释动作或推荐合适的服务。

小结

text.set_value 的参数面非常精简——只有一个必填的 value 字符串参数,加上灵活的 target 选择——但它的约束规则(pattern、最小/最大长度)由实体侧强制执行。掌握「实体域 + value 约束 + target 类型」这三点,你就能在 UI 和 YAML 中自如地把这段动作嵌入自动化与脚本,实现显示屏留言、灯牌标签更新等文本写入场景。

登录后查看全文
home-assistant.io