第2章 YAML 语法入门
YAML 语法
Home Assistant 中的大多数功能都可以通过用户界面直接配置,无需触碰任何 YAML 文件。少数高级功能和部分集成仍需在 configuration.yaml 中手动填写条目,本页将介绍这些场景下所需的 YAML 语法基础。
YAML 风格指南
本页提供 Home Assistant 所用 YAML 语法的高层入门。如需更详细的说明和更多示例,请参阅面向 Home Assistant 开发者的 YAML 风格指南。
第一个示例
下面的 YAML 示例假设你要配置 notify 集成,并指定使用 pushbullet 平台。
notify:
platform: pushbullet
api_key: "o.1234abcd"
name: pushbullet
集成(Integration)提供某项功能的核心逻辑(例如 notify 负责发送通知)。平台(Platform)则负责连接具体的软件或硬件服务(例如 pushbullet 对应 pushbullet.com 提供的服务)。
YAML 语法的基石是块级集合(Block Collections)和包含键值对的映射(Mappings)。集合中的每一项以 - 开头,映射则采用 key: value 格式。这有点像哈希表,更准确地说类似 Python 中的字典。它们也可以嵌套使用。注意:若指定了重复的键,系统会使用最后一个值。
YAML 中的缩进
在 YAML 中,缩进对于定义层级关系至关重要。缩进的行嵌套在比它高一级的行内部。在上面的示例中,platform: pushbullet 是 notify 集成的一个属性(嵌套在其内部)。
如果编辑器没有使用固定宽度字体,获取正确的缩进可能会很棘手。YAML 禁止使用制表符(Tab)进行缩进。惯例是每个缩进层级使用 2 个空格。
注释
紧跟在 # 后面的文本是注释,系统会忽略它们。注释用通俗语言解释代码块的目的,方便未来的你自己或其他查看该文件的人理解。
带注释和嵌套的示例
下一个示例展示了一个使用块级集合定义选项值的 input_select 集成。其他属性(如 name:)使用映射格式指定。注意第二行只有 threat: 而没有同行值。这里 threat 是 input_select 的名称,其具体值是下方所有嵌套内容。
input_select:
threat:
name: "Threat level"
# 使用集合定义 options
options:
- 0
- 1
- 2
- 3
initial: 0
嵌套映射示例
以下示例展示了在映射中嵌套映射集合的情况。在 Home Assistant 中,这将创建两个传感器,它们都使用 MQTT 平台,但 state_topic(MQTT 传感器使用的属性之一)的值不同。
sensor:
- platform: mqtt
state_topic: "sensor/topic"
- platform: mqtt
state_topic: "sensor2/topic"
包含变量
环境变量
在 Home Assistant Core 安装中,你可以使用 !env_var 引入系统环境变量中的值。注意,这仅在可以指定这些变量的 Home Assistant Core 安装场景中有效。普通 Home Assistant 用户建议使用 !include 语句替代。
example:
password: !env_var PASSWORD
默认值
如果环境变量未设置,你可以指定一个回退的默认值。
example:
password: !env_var PASSWORD default_password
包含整个文件
为了提高可读性,你可以使用 !include 语法将某些领域(domains)从主配置文件中拆分出来。
light: !include lights.yaml
关于此功能的更多信息,也可参见拆分配置。
常见问题
发现字符 ‘\t’
如果你看到以下消息:
found character '\t' that cannot start any token
这意味着你误用了制表符,而应该使用空格。
大小写敏感
Home Assistant 对大小写敏感。状态值可以使用任意大小写,因此 'on' 与 'On' 或 'ON' 不同。另一方面,实体 ID 始终为小写,因此引用 binary_sensor.Front_Door 不会匹配实际的实体 binary_sensor.front_door。如果你不确定某个状态使用的大小写,请查看 设置 > 工具 > 状态 中 Home Assistant 如何报告它。
布尔值
YAML 将 Y、true、Yes、ON 都视为 true,将 n、FALSE、No、off 视为 false。这意味着如果你要将实体状态设置为 on,必须加引号写成 'on',否则它会被解释为设置为 true。同样适用于 off。未加引号可能导致如下错误:
not a valid value for dictionary value @ data
验证 YAML 语法
面对如此多的缩进规则,出错在所难免。检查 YAML 语法是否正确(验证)的最佳方式取决于你使用的编辑器。我们无法在此列出所有工具。如果你直接在 Home Assistant 中编辑文件,请参阅验证配置部分。
相关主题
相关链接
帮助我们改进文档
本页对您有帮助吗?您可以建议编辑此页面,或提供/查看此页面的反馈。