跳过主要内容

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_IDbinary_sensor.motion

# 坏的
-别名“测试”
扳机
-平台状态
ENTITY_IDbinary_sensor.motion
(健康)状况[[这是给予的

弦(续)

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

  • 实体ID(例如,binary_sensor.motion
  • 实体属性(例如,温度
  • 设备ID
  • 区域ID
  • 平台类型(例如,,,,,转变
  • 条件类型(例如,numeric_state,,,,状态
  • 触发平台(例如,状态,,,,时间
  • 服务名称(例如,light.turn_on
  • 设备类(例如,问题,,,,运动
  • 事件名称
  • 接受有限的一组可能的硬编码值的值。例如,模式在自动化中。
# 好的
行动
-服务notify.frenck
数据
信息“你好呀!”
-服务light.turn_on
目标
ENTITY_IDlight.office_desk
aket_id客厅
数据
过渡10

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

服务目标

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

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

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

# 好的
行动
-服务light.turn_on
目标
ENTITY_IDlight.living_room
-服务light.turn_on
目标
aket_idlight.living_room
-服务light.turn_on
目标
aket_id客厅
ENTITY_IDlight.office_desk
设备ID21349287492398472398

# 坏的
行动
-服务light.turn_on
ENTITY_IDlight.living_room
-服务light.turn_on
数据
ENTITY_IDlight.living_room

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

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

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

  • 将多个值放入单个标量值(逗号分隔字符串)中。
  • 如果使用列表,则必须是块样式。
  • 不应使用具有单个标量值的列表。
  • 允许使用单个标量值。
# 好的
ENTITY_IDlight.living_room
ENTITY_ID
-light.living_room
-Light.Office

# 坏的
ENTITY_IDlight.living_room,,,,Light.Office
ENTITY_ID[[light.living_room,,,,Light.Office这是给予的
ENTITY_ID
-light.living_room

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

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

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

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

# 好的
行动
-服务light.turn_on
目标
ENTITY_IDlight.living_room

# 坏的
行动
服务light.turn_on
目标
ENTITY_IDlight.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(),以避免实体尚未准备就绪时发生错误和错误消息(例如,在家庭助理启动期间)。必威是什么

Baidu