第3章 YAML 中的模板
大多数情况下,模板都写在 YAML 文件里。YAML 对引号和多行文本有自己的解析规则,这些规则与模板交互时很容易让人踩坑。本页整理了常见的陷阱,以及如何绕过它们的写法。
被 YAML 坑到不用不好意思,谁都逃不过。当 Home Assistant 拒绝加载配置且报错信息令人费解时,随时回来看这一页。
引号规则
单行模板必须加引号。单引号(')或双引号(")都可以。
# 正确:模板被引号包裹
value_template: "{{ states('sensor.temp') | float > 20 }}"
结果:True(当传感器报告的值超过 20 时)
如果不加引号,YAML 会把 {{ 当作 flow-style 映射的开头并解析失败。此时报错信息往往很令人困惑,所以如果某项配置加载失败,请先检查引号是否配对。
单引号和双引号的作用基本相同,区别在于反斜杠(\)的处理。在双引号内,YAML 将反斜杠视为转义序列的起始符,例如 \n 表示换行。如果反斜杠后跟的不是已知的转义序列(例如正则表达式中的 \d),配置就会加载失败。而在单引号内,反斜杠被视为普通字符。如果模板包含反斜杠,请用单引号包裹整个模板,模板内部使用双引号,或者改用多行模板。
模板内的引号
如果模板本身包含引号,请换用另一种引号包裹,以避免冲突。
# 模板包含单引号,因此外层用双引号包裹
value_template: "{{ is_state('light.kitchen', 'on') }}"
# 模板包含双引号,因此外层用单引号包裹
value_template: '{{ states["sensor.temp"] }}'
结果:两种模板都能正确求值,引号不会冲突。
如果同一个模板需要同时使用两种引号,请改用多行字符串(见下文)。
多行模板
当模板超过一行时,加引号会变得繁琐。YAML 提供两种多行文本样式,无需引号:>(折叠)和 |(保留)。根据期望的输出格式选择其一。
> 样式(折叠)会将多行内容合并为一行,行间用单个空格分隔。适用于模板本身是一长段代码、为了版面整洁而手动换行的情况。
value_template: >
{{
states('sensor.temp') | float(0) > 20
and states('sensor.humidity') | float(0) < 60
}}
结果:True(当两个条件都满足时)
| 样式(保留)会保留你写下的所有换行符。适用于输出需要保留换行符的情况,例如多行通知消息。
message: |
Today's summary:
Temperature: {{ states('sensor.temp') }}°C
Humidity: {{ states('sensor.humidity') }}%
结果:
Today's summary:
Temperature: 22.5°C
Humidity: 54%
>- 和 |- 变体
尾部的 - 会移除 YAML 文本末尾的换行符。在 value_template 中经常看到这种写法。对于模板结果来说,区别不大:Home Assistant 无论如何都会去除结果首尾的空白字符。
value_template: >-
{% if states('sensor.outdoor_temp') | float(0) < 0 %}
freezing
{% else %}
not freezing
{% endif %}
结果:not freezing
多行块内的缩进
在 | 或 > 块中,YAML 根据第一个非空行的缩进来确定基准。后续所有行的缩进必须不少于这个基准。如果混用缩进,YAML 会在缩进较小的那一行截断该块,把剩余部分当作新的键来解析。
# 错误:第二行缩进小于第一行
message: |
Status Report
Temperature: 22
# 正确:所有行共享相同的基准缩进
message: |
Status Report
Temperature: 22
结果:
Status Report
Temperature: 22
如果需要对特定行增加更多缩进(例如居中文本),请在模板内容内部实现,而不是靠增加 YAML 的缩进。
常见错误
- 单行模板未加引号。YAML 会抱怨
{{。请加上引号。 - 开头加了引号但忘了闭合。长模板中容易犯这个错。拿不准时,改用
>-多行块。 - 需要保留换行却用了
>。输出会变成一行。应使用|。 |或>块内缩进不一致。YAML 会在最小缩进处截断块。
当模板拒绝工作时,请参考“Debugging templates”页面,了解如何缩小问题范围。
下一步
- 要了解核心语言本身,查看“Template syntax”。
- 如果模板行为异常,参考“Debugging templates”页面的排查流程。
- 寻找可直接改编的现成示例,查看“Common template patterns”。
仍然卡住了?
Home Assistant 社区乐于助人:加入 Discord 进行实时交流,在社区论坛发帖并附上你的模板及期望结果,或者在我们的 subreddit /r/homeassistant 分享。
提示
ChatGPT 或 Claude 等 AI 助手也能解释或修复模板,只要你用自然语言描述你想要什么。
相关主题
- Template syntax
- Debugging templates
- Yaml configuration
帮助我们改进文档
此页面是否有帮助?
建议编辑此页面,或提供/查看此页面的反馈。