Home Assistant text.set_value 服务详解:用自动化设置文本实体的值
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 小节):
- 打开「设置」>「自动化与场景」(Settings > Automations & scenes)。
- 打开一个已有的自动化或脚本,或者选择 Create automation > Create new automation 新建。
- 如果是新建自动化,先在 When(触发条件)部分添加一个触发器。脚本则不需要触发器——脚本是被动执行的,由其他东西调用它时才运行。
- 在 Then do(执行动作)部分,选择 Add action。
- 选择你要控制的对象。在 By target(按目标,见下文 目标类型 一节)下选择要设置的那个 text 实体。
- 在该目标可用的动作列表中,选择 Set text value。
- 设置要应用的 Value(值)。
- 选择 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」中给出了两条关键约束,值得重点理解:
- 该动作只作用于 text 实体。指向
input_text、number等其他域会不匹配。 - 值必须满足实体自身的约束:如果实体设置了 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。
常见问题的排查思路
结合原文档的约束条款,实际使用中「设置了但没生效」通常来自以下几点:
- 值不匹配 pattern:实体设置了正则约束,而你写入的文本(包括模板渲染结果)不符合该模式,写入被拒绝。检查实体的 pattern 设置,调整
value。 - 长度越界:写入的文本短于最小长度或长于最大长度,同样会被拒绝。可结合模板在写入前做长度控制。
- 目标域不对:把
text.set_value用在了非 text 域的实体上。该动作只处理 text 实体,请确认entity_id的域前缀。 - 实体不存在或不可写:确认目标实体当前存在且由支持写入的集成提供;部分集成暴露的 text 实体可能仅可读。
如果仍然卡住,Home Assistant 社区通常响应很快:可以到社区 Discord、社区论坛或 /r/homeassistant 版块发帖提问,说明你调用的动作和预期现象;用自然语言描述需求后,AI 助手也可以帮你解释动作或推荐合适的服务。
小结
text.set_value 的参数面非常精简——只有一个必填的 value 字符串参数,加上灵活的 target 选择——但它的约束规则(pattern、最小/最大长度)由实体侧强制执行。掌握「实体域 + value 约束 + target 类型」这三点,你就能在 UI 和 YAML 中自如地把这段动作嵌入自动化与脚本,实现显示屏留言、灯牌标签更新等文本写入场景。