YAML样式指南

除了我们的一般文档标准，我们还有一套用于记录YAML片段的标准。此页面上描述的标准适用于整个项目中我们所有基于YAML的代码，主要关注文档。

我们的YAML标准为我们的最终用户提供了一致的外观，最佳实践和解决YAML问题的统一方法。

Yaml

本节是关于基本YAML使用情况的，因此不是特定于家庭助理的。必威是什么

缩进

必须使用两个空间的凹痕。

＃ 好的
例子：
一：1

＃ 坏的
例子：
坏的：2

               
              

布尔人

我们应该避免在YAML中使用真实的布尔值。他们经常抛弃YAML新手。因此，我们只允许使用真的和错误的作为布尔值，在较低的情况下。

这也使其与YAML 1.2规格兼容，因为该版本对几个无引用的真实布尔值的支持下降（例如，例如，y，，，，n，，，，是的，，，，不，，，，上，，，，离开和类似）。

＃ 好的
一：真的
二：错误的

＃ 坏的
一：真的
二：上
三：是的

               
              

注释

在YAML块中添加注释确实可以帮助读者更好地理解示例。

评论的压痕级必须与当前的压痕级相匹配。最好的是，评论在该评论应用的行上方写，否则在较小的显示器上可能很难阅读行。

评论应从大写字母开始，并在评论之间有一个空间＃以及评论的开始。

＃ 好的
例子：
＃ 评论
一：真的

＃可接受，但更喜欢以上
例子：
一：真的＃ 评论

＃ 坏的
例子：
＃ 评论
一：错误的
＃评论
二：错误的
＃ 评论
三：错误的

               
              

序列

YAML中的序列也称为列表或数组。在家庭助理世界必威是什么中，我们将它们称为最终用户文档中的列表。这起源于python语言开发了家庭助理核心。必威是什么

序列可以用两种不同的样式编写；块和流风格。我们更喜欢使用块样式序列。

块样式序列

块样式序列需要在其属于的钥匙下缩进。

＃ 好的
例子：
-1
-2
-3

＃ 坏的
例子：
-1
-2
-3

               
              

流样式序列

应避免使用流风格。虽然简单，简短和干净，并且其中包含较长的数据，但很难阅读。

如果使用，流风格序列在每个逗号之后都有空间，，，，在打开和关闭之前没有空白：

＃ 好的
例子：[[1，，，，2，，，，3这是给予的

＃ 坏的
例子：[[1，，，，2，，，，3这是给予的
例子：[[1，，，，2，，，，3这是给予的
例子：[[1，，，，2，，，，3这是给予的
例子：[[“ Light.living_room_window”，，，，“ Light.living_room_corner”，，，，“ light.living_room_table”这是给予的

               
              

映射

YAML中的映射也称为关联阵列，哈希表，键/值对，集合或字典。在家庭助理世界必威是什么中，我们将它们称为最终用户文档中的映射。

映射可以用不同的样式编写，但是，我们只允许使用块样式映射。不允许流动风格（看起来像JSON）。

＃ 好的
例子：
一：1
二：2

＃ 坏的
例子：{一：1，，，，二：2}

               
              

空值

零值应被隐式标记。应避免使用显式零值（〜和无效的）。

＃ 好的
例子：

＃ 坏的
例子：〜
例子：无效的

字符串

优选用双引号引用字符串（“）。

＃ 好的
例子：“你好呀！”

＃ 避免
例子：你好呀呢

＃ 坏的
例子：'你好呀！'

多行字符串

避免使用\ n或者，如果可能的话，YAML配置中的其他新行指标。同样适用于避免长长的单线字符串。

相反，使用文字样式（保留新线条）和折叠样式（不保留新线条）字符串。

＃ 好的
LILLEAL_EXAMPE：|
此示例是YAML中字面块标量风格的示例。
它使您可以将字符串分为多行。
folded_example：>
此示例是YAML中折叠块标量样式的示例。
它使您可以将字符串分为多行，但是它神奇地
删除YAML中放置的所有新线条。

＃ 坏的
LILLEAL_EXAMPE：“此示例是YAML中字面块标量样式的示例。\ nit允许您将字符串分为多行。\ n””
folded_example_same_as：“此示例是YAML中折叠块标量样式的示例。它使您可以将字符串分为多行，但是，它神奇地删除了放置在YAML中的所有新线条。\ n””。

               
              

在上面的示例中，使用了无碎操作员（|，，，，>）。这是首选，除非示例需要对结束新行的不同处理。在这种情况下，使用脱衣舞操作员（| -，，，，> -：没有尾随的新线路，从末端删除了任何其他新行）或保持操作员（|+，，，，| -：尾随新线路，并从末端保持所有其他新线路）。

其他字符串指导

家庭助理必威是什么YAML部分提供了有关如何处理家庭助理配置示例中字符串的其他准则。

必威是什么YAML家庭助理

在家庭助理中，必威是什么我们还可以通过不同的方式来完成一些事情，同时仍然遵守上述样式。这部分是为了解决这个问题。

默认值

使用默认值的配置选项不应是示例的一部分。除非该示例专门用于教育该选项。

例如，我们的（健康）状况自动化中的选项是可选的，是空列表[]默认。

＃ 好的
-别名：“测试”
扳机：
-平台：状态
ENTITY_ID：binary_sensor.motion

＃ 坏的
-别名：“测试”
扳机：
-平台：状态
ENTITY_ID：binary_sensor.motion
（健康）状况：[[这是给予的

               
              

弦（续）

正如第一章所写的那样，琴弦最好用双引号唤起。但是，以下值类型免于此规则，这使我们的示例更具可读性：

实体ID（例如，binary_sensor.motion）
实体属性（例如，温度）
设备ID
区域ID
平台类型（例如，光，，，，转变）
条件类型（例如，numeric_state，，，，状态）
触发平台（例如，状态，，，，时间）
服务名称（例如，light.turn_on）
设备类（例如，问题，，，，运动）
事件名称
接受有限的一组可能的硬编码值的值。例如，模式在自动化中。

＃ 好的
行动：
-服务：notify.frenck
数据：
信息：“你好呀！”
-服务：light.turn_on
目标：
ENTITY_ID：light.office_desk
aket_id：客厅
数据：
过渡：10

＃ 坏的
行动：
-服务：“ notify.frenck”
数据：
信息：你好呀呢

               
              

服务目标

如果您想为实体ID发射服务呼叫（例如，打开灯），可以以三种不同的方式进行。

实体ID可以指定为服务级别的属性，这是在服务调用中发送的数据的一部分或服务目标中的实体。

服务目标是最现代的方式，允许人们针对实体，设备或区域的服务呼叫。因此，目标是可用选项中最灵活的目标，并且是应使用的选项。

＃ 好的
行动：
-服务：light.turn_on
目标：
ENTITY_ID：light.living_room
-服务：light.turn_on
目标：
aket_id：light.living_room
-服务：light.turn_on
目标：
aket_id：客厅
ENTITY_ID：light.office_desk
设备ID：21349287492398472398

＃ 坏的
行动：
-服务：light.turn_on
ENTITY_ID：light.living_room
-服务：light.turn_on
数据：
ENTITY_ID：light.living_room

               
              

接受标量或标量列表的属性

必威是什么家庭助理有很多地方可以访问标量值或标量值列表。此外，有时，它甚至接受逗号分隔的字符串值作为列表。

如果接受单个值或标量值列表，则适用以下内容：

将多个值放入单个标量值（逗号分隔字符串）中。
如果使用列表，则必须是块样式。
不应使用具有单个标量值的列表。
允许使用单个标量值。

＃ 好的
ENTITY_ID：light.living_room
ENTITY_ID：
-light.living_room
-Light.Office

＃ 坏的
ENTITY_ID：light.living_room，，，，Light.Office
ENTITY_ID：[[light.living_room，，，，Light.Office这是给予的
ENTITY_ID：
-light.living_room

               
              

接受映射或映射列表的属性

必威是什么家庭助理具有接受映射或映射列表的属性。众所周知的例子是：（健康）状况，，，，行动，，，，序列。

如果属性接受单个映射或映射列表，则必须使用映射列表，即使传递了单个映射。

这使得更容易理解，可以在其中添加更多项目，并且更容易将单个项目复制并粘贴到您自己的代码中。

＃ 好的
行动：
-服务：light.turn_on
目标：
ENTITY_ID：light.living_room

＃ 坏的
行动：
服务：light.turn_on
目标：
ENTITY_ID：light.living_room

               
              

模板

必威是什么家庭助理模板很强大，但是对于经验不足的用户来说，它们确实很困惑或难以理解。因此，如果有纯YAML版本，应避免使用模板的使用。

此外，模板的使用需要在我们的文档中进行额外的逃避，以避免我们的网站代码将其混淆为液体语法。通常，避免模板消除了需要额外逃脱的需要。

＃ 好的
（健康）状况：
-（健康）状况：numeric_state
ENTITY_ID：太阳
属性：海拔
以下：4

＃ 坏的
（健康）状况：
-（健康）状况：模板
value_template：“ {{state_attr（'sun.sun'，'高程'）<4}}}”

               
              

引用风格

模板是字符串，因此是双重引用的。因此，应该在模板内使用单引号。

＃ 好的
例子：“ {{{'some_value'== some_other_value}}”

＃ 坏的
例子：'{{“ some_value” == some_other_value}}'

模板字符串长度

应避免模板中的长行并在多条线上划分，以更清楚发生的事情并保持它们可读。

有关多行字符串格式的更多信息，请参见上面的字符串章节。

＃ 好的
value_template：>-
{{
IS_STATE（'Sensor.bedroom_co_status'，，，，'好的'）
和is_state（'sensor.kitchen_co_status'，，，，'好的'）
和is_state（'Sensor.wardrobe_co_status'，，，，'好的'）
}}

＃ 坏的
value_template：“ {{is_state（'sensor.bedroom_co_status'，'ok'）和is_state（'sensor.kitchen_co_status'，'ok'）和is_state（'sensor.wardrobe_co_co_status'ok'ok'ok'ok'ok'）}}}}}}”

               
              

短风格条件语法

优先使用速记样式模板过于表达的格式，因为它们提供了更干净的语法。

＃ 好的
（健康）状况：“ {{{some_value == some_other_value}}”

＃ 坏的
（健康）状况：
-（健康）状况：模板
value_template：“ {{{some_value == some_other_value}}”

               
              

过滤器

绕过过滤管标记|是必须的。如果这使得可读性不清楚，建议使用其他括号。

＃ 好的
（健康）状况：
-“ {{{some_value | float}}””
-“ {{some_value ==（some_other_value | some_filter）}}}}”

＃ 坏的
（健康）状况：
-“ {{some_value == some_other_value | some_filter}}}”
-“ {{some_value ==（some_other_value | some_filter）}}}}”

               
              

访问状态和状态属性

如果有帮助方法，我们不允许直接使用状态对象。

例如;不要使用states.sensor.temperature.state，而是使用状态（“传感器”）。

＃ 好的
一：“ {{states（'sensor.temperature'）}}}”
二：“ {{state_attr（'climate.living_room'，'温度'）}}}”

＃ 坏的
一：“ {{states.sensor.temperature.state}}}”
二：“ {{states.climate.living_room.attributes.temperature}}}””

               
              

这适用于状态（），，，，is_state（），，，，state_attr（）和is_state_attr（），以避免实体尚未准备就绪时发生错误和错误消息（例如，在家庭助理启动期间）。必威是什么