语言基础知识

bookmark_border 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

了解 YAML

YAML 是一种用于指定软件配置的常用语言。它提供了一种清晰且人类可读的方式来表示结构化信息。在创建第一个脚本化自动化流程之前，您需要先了解一些有关 YAML 的基本知识。如需详细了解 YAML，请参阅版本 1.1 规范。

键值对

YAML 文档基本上是键值对的集合。在以下示例中，键为 name，值为 TV on lights off。键和值之间以英文冒号加空格分隔。这两个字符对于格式正确的 YAML 都是必需的。

name: TV on lights off

值

与键关联的值可以像字符串、数字或日期一样基本，也可以像另一组键值对一样复杂。

字符串

如果字符串值以以下字符之一开头：[、{、"、' 或 #，或者字符串包含 :（冒号后跟空格），则必须使用引号将该字符串值引起来。

单引号和双引号均可接受，但结束引号必须与起始引号一致。

正确的引用：

name: 'TV on lights off'

name: "TV on lights off"

引用不正确（引号不匹配）：

name: 'TV on lights off"

对于所有其他类型的字符串，引号都是可选的。

如果您需要多行字符串，请参阅 YAML 规范中有关多行标量的部分。

name: "[1] TV"
name: '{1} TV'
name: '#TV'
name: '"1" TV'
name: "'1' TV"
name: "\"1\" TV"
name: "TV: bedroom"

嵌套键值对

在此示例中，键 metadata 的值是一个包含两个键值对（name 和 description）的列表：

metadata:
  name: TV on lights off
  description: Turn off lights when TV turns on

缩进

YAML 使用缩进来表示结构。在前面的示例中，name 和 description 缩进了两个空格，表示它们是键 metadata 的子项。

YAML 中的缩进非常严格。子结构的缩进必须比其父结构更深，并且同一级别的键值对必须具有相同的缩进。

metadata:
  name:
    en: TV on lights off
  description:
    en: Turn off lights when TV turns on

多个值

如果某个给定键有多个值，则每个值都会列在新的一行中，并且每行都以短划线和空格开头。在以下示例中，有两个列表：

1. 一个自动化操作可以有多个 starters，因此第一个启动方式以短划线和空格开头。
2. weekday 可以有多个值，因此每个值都会进一步缩进，并以短划线和空格开头。

starters:
- type: time.schedule
  at: SUNSET
  weekday:
  - MONDAY
  - THURSDAY
  state: on

评论

# 后面的任何文本都被视为注释，并会被自动化引擎忽略。

以 # 开头的行是注释。

注释可以与脚本内容显示在同一行上，但 # 必须以空格开头。

# This is a comment. It will be ignored.
name: chromecast #This is a TV.

自动化脚本

自动化脚本语法的规范称为架构。

自动化操作架构定义了以下几种数据结构：

• 单个键值对称为字段。
• 由架构定义的一组字段称为 Struct。

结构体

自动化脚本语言定义了多个标准“块”或数据结构，称为 Struct。

请查看 automation 结构，其中定义了四个字段：

参考文档 部分提供了所有可用结构的架构定义。

键名在给定的结构体中是唯一的，并且区分大小写。

可能的值类型包括：

• 一种基元类型：布尔值、数字、字符串、时间等。
• 一种结构体类型：字段的集合。
• 相应数据类型的数组。数组用 [] 表示。例如，[string] 是一个字符串数组，而 [Starter] 是一个 Starter 结构体数组。
• 其他特殊类型：实体、FieldPath。

每个字段的说明都包含重要信息，包括：

• 必需与可选，用于指明相应字段是强制性字段还是可以跳过。
• 字段依赖项。只有可选字段具有依赖项。此属性用于描述使用相应字段时的其他检查，例如仅当设置了字段 A 时才使用字段 B，或者使用字段 A 时，请勿设置字段 B 或字段 C。
• 可能的值。例如，字符串类型 Enum 字段的有限值集，或数字类型字段中可能使用的数字范围。

类型化结构体

某些结构可以表示基于时间安排或设备状态变化的启动方式。每种类型的 starter 都必须提供一组不同的字段。

# A time schedule starter.
starter:
  type: time.schedule
  at: 10:00

# A device state change starter.
starter:
  type: device.state.OnOff
  device: TV - Living Room
  state: on
  is: true

starter 是一种类型化结构体，由 type 字段中的其他子结构体（例如 time.schedule 或 device.state.OnOff）扩展，以提供不同的功能。condition 和 action 结构体也是类型化的。

结构中的其他字段必须遵循子结构 (type) 规范。例如，当使用 device.state.OnOff 作为 type 时，只有为该类型指定的字段 在该 starter 结构体中有效。

数组

在 YAML 中，值数组以 -（短划线后跟一个空格）开头。该数组可以包含多个结构体值或多个原始值。但数组中的值必须属于同一类型。

如果数组只包含一个元素，您可以省略短划线和空格：

# The starters field accepts an array of Starter Structs.
# This is the standard format.
starters:
- type: time.schedule
  at: sunset
- type: time.schedule
  at: sunrise

# The dash can be omitted if the array only has one item.
# This is also valid.
starters:
  type: time.schedule
  at: sunset

自动化脚本不支持多维数组（例如 [[1, 2], [3, 4]]）。语言解析器会自动将多维数组扁平化为一维数组，在本例中为 [1, 2, 3, 4]。

# INVALID: multi-dimensional array
- - 1
  - 2
- - 3
  - 4

原初

自动化脚本架构支持以下基本数据类型：

颜色

颜色可以通过以下三种方式之一指定：使用 ColorHex 或 ColorTemperature 原始类型，或者使用复合类型 SpectrumHSV。

SpectrumHSV

SpectrumHSV 类型使用三个数字字段指定颜色：

• 色调对应于颜色波长。
• 饱和度表示颜色的强度。
• 明度表示颜色的相对亮度或暗度。

动态

有时，键的数据类型并不固定。它可以是基于其他字段的值的某种原始类型。

动态数据类型字段的一个示例是 is。实际类型由 type 和 state 字段的值共同决定。

# The 'is' field accepts a number type.
type: device.state.Volume
device: My TV - Living Room
state: currentVolume
is: 1

# The 'is' field accepts a boolean type.
type: device.state.OnOff
device: My TV - Living Room
state: on
is: false

实体

一种特殊的字符串格式，用于唯一标识用户拥有的实体（例如设备或房间）。

设备是自动化操作中最常用的实体。实体字符串格式为 device name - room name。

# The device field accepts a Device Entity type.
type: device.state.Volume
device: My TV - Living Room
state: currentVolume
is: 1

FieldPath

一种特殊的字符串格式，用于在数据载荷中查找数据。在以下示例中，currentVolume 是 state 字段的 FieldPath。

# The state field accepts a FieldPath type.
starters:
  type: device.state.Volume
  device: My TV - Living Room
  state: currentVolume
  is: 5

其他 FieldPath 可能需要多个级别才能到达所需项，并且起始和操作之间的格式有所不同。

启动器使用点表示法，整个路径位于同一字段中。这主要是为了在初始逻辑中进行比较。例如，如需使用色温作为起始值，您可以使用 color.colorTemperature 作为状态：

starters:
- type: device.state.ColorSetting
  device: My Device - Room Name
  state: color.colorTemperature
  is: 2000K

不过，操作使用嵌套字段。若要将灯泡的颜色更改为蓝色，您必须执行以下操作，而不是使用 color.name 和 is: blue：

actions:
- type: device.command.ColorAbsolute
  devices: My Device - Room Name
  color:
    name: blue