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()
,以避免实体尚未准备就绪时发生错误和错误消息(例如,在家庭助理启动期间)。必威是什么