进阶 www.home-assistant.io 2026-11-16 12:36:09 · 7 阅读

第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

帮助我们改进文档

此页面是否有帮助?
建议编辑此页面,或提供/查看此页面的反馈。

编辑 | 提供反馈 | 查看已提交的反馈

评论 (0)