iOS DSL 指南

请参阅以下指南，了解如何使用各种自动化 DSL 节点来构建自动化。

所有自动化 DSL 都放置在单个 automation 节点内。automation 节点构成外部 Swift 语言上下文与嵌入式 DSL 上下文之间的边界。

顺序流程

顺序流程是默认的自动化流程类型。

顺序 DSL 示例

下面是一个非常基本的自动化 DSL 模板，它使用由启动器、条件和操作组成的顺序流程：

import GoogleHomeSDK
import GoogleHomeTypes

automation (
...
) {
  starter(...)
  condition {...}
  action {...}
}

您可以通过添加其他节点来优化此图表。

入门版

启动方式节点用于定义触发自动化操作的初始情况。例如，状态或值的变化。自动化必须至少有一个启动器，否则将无法通过验证。如需向自动化操作添加多个启动器，您必须使用 select 节点。

基于特征属性的启动器

声明基于特征属性的起始节点时，请指定：

  • 设备
  • 特征所属的设备类型
  • 相应特征
starter(
  thermostat,
  Matter.TemperatureSensorDeviceType.self,
  Matter.TemperatureMeasurementTrait.self
)

设备类型参数是必需的，因为它可以让您指定自动化所针对的设备中的哪个设备类型。例如，某个设备可能由 FanDeviceType 和 HeatingCoolingUnitDeviceType 组成，这两者都包含 OnOffTrait 特征。通过指定设备类型，可以明确设备中的哪个部分触发自动化操作。

基于事件的启动器

声明基于事件的起始节点时，请指定：

  • 设备
  • 特征所属的设备类型
  • 活动
starter(
  doorbell,
  Google.GoogleDoorbellDeviceType.self,
  Google.DoorbellPressTrait.DoorbellPressedEvent
)

基于结构和事件（含参数）的初始代码

某些事件可以包含参数，因此这些参数也需要包含在初始代码中。

例如，此启动方式使用 TimeTrait 的 ScheduledEvent 在上午 7:00 激活自动化操作：

typealias TimeTrait = Google.TimeTrait

let earlyMorning = starter(
  structure,
  TimeTrait.ScheduledEvent.self
) {
  TimeTrait.ScheduledEvent.clockTime(TimeOfDay(hours: 7, minutes: 0))
}

手动启动器

手动启动器是一种特殊类型的启动器，可让用户手动运行自动化操作。

声明手动启动器时：

如果将手动启动器与另一个启动器一起放置在 select 流程中，手动启动器会替换另一个启动器：

select {
  manualStarter()
  starter(
    thermostat,
    Matter.TemperatureSensorDeviceType.self,
    Matter.TemperatureMeasurementTrait.self
  )
}

请注意，手动启动器之后的任何 condition 节点都会被评估，并且可能会阻止自动化执行，具体取决于 condition 表达式。

将手动启动器与条件启动器分开

一种结构化自动化操作的方式是，让 condition 节点不会阻塞通过手动启动方式激活的自动化操作，方法是将其他启动方式及其 condition 放在单独的顺序流程中：

import GoogleHomeSDK
import GoogleHomeTypes

automation (
...
) {

  select {
    sequential {
      starter(...)
      condition {...}
    }
    sequential {
      manualStarter()
    }
  }
  action {...}

}

引用属性的值

如需在表达式中使用属性的值，请使用以下语法。

使用 stateReader：

typealias TimeTrait = Google.TimeTrait

let time = stateReader(structure, TimeTrait.self)
time
let currTime = time.currentTime

使用 starter：

typealias LaundryWasherDeviceType = Matter.LaundryWasherDeviceType
typealias OnOffTrait = Google.OnOffTrait

let starterNode = starter(device1, LaundryWasherDeviceType.self, OnOffTrait.self)
starterNode
condition {
  starterNode.onOff.equals(true)
}

条件节点和表达式

条件节点表示一个决策点，用于确定自动化流程是否继续。一个自动化流程可以包含多个 condition 节点。 如果任何 condition 节点的表达式的计算结果为 false，则整个自动化流程的执行结束。

在 condition 节点中，您可以使用各种运算符组合多个条件，只要表达式的计算结果为单个布尔值即可。如果结果值为 true，则表示满足条件，自动化流程会继续执行下一个节点。如果值为 false，自动化操作会在该点停止执行。

表达式的构成方式与 Swift 中的表达式类似，可以包含数字、字符、字符串和布尔值等基本值，以及枚举值。使用圆括号对子表达式进行分组，可控制它们的求值顺序。

以下是一个 condition 的示例，它将多个子表达式合并为一个表达式：

condition {
  let exp1 = starterNode.lockState.equals(.unlocked)
  let exp2 = stateReaderNode.lockState.equals(true)
  let exp3 = occupancySensingDevice.occupied.notEquals(0)
  (exp1.and(exp2)).or(exp3)
}

您可以通过启动器引用所访问特征的值：

typealias OnOffTrait = Matter.OnOffTrait

let starterNode = starter(device, OnOffTrait.self)
starterNode
condition {
  starterNode.onOff.equals(true)
}
val starterNode = starter<_>(device, OnOff)
condition() { expression = starterNode.onOff equals true }

stateReader

在 condition 节点中引用特征属性值的另一种方法是使用 stateReader 节点。

为此，请先在 stateReader 节点中捕获特征属性值。stateReader 将 structure 和特征作为实参：

typealias ActivatedCarbonFilterMonitoringTrait = Matter.ActivatedCarbonFilterMonitoringTrait

let filterMonitoringState = stateReader(structure, ActivatedCarbonFilterMonitoringTrait.self)

然后在 condition 节点中引用 stateReader：

condition {
filterMonitoringState.changeIndication.equals(.warning)
}

使用比较和逻辑运算符，可以在 condition 节点中使用多个 stateReaders：

typealias ArmDisarm = Google.ArmDisarmTrait
typealias DoorLockDevice = Matter.DoorLockDeviceType
typealias DoorLock = Matter.DoorLockTrait

let armState = stateReader(doorLock, DoorLockDevice.self, ArmDisarm )
let doorLockState = stateReader(doorLock, DoorLockDevice.self, DoorLock)
armState
doorLockState
condition {
  let exp1 = armState.armState
  let exp2 = doorLockState.lockState
  exp1.and(exp2)
}

条件时长

除了在条件中使用布尔表达式外，您还可以指定一个时间范围，只有在该时间范围内表达式为 true 时，系统才会运行自动化操作。例如，您可以定义一个仅在灯亮了 10 分钟后触发的条件。

condition(for: .seconds(600)) {
lightStateReader.onOff.equals(true)
}

时长可以介于 1 分钟到 30 分钟之间。

操作节点

操作节点是自动化操作执行工作的位置。在此示例中，操作会调用 AssistantBroadcastTrait 的 broadcast() 命令：

action(speaker, SpeakerDeviceType.self) {
  Google.AssistantBroadcastTrait.broadcast(msg: "Oven Cycle Complete")
}
上一页
DSL 概念
下一页
复杂的自动化操作