适用于复杂自动化操作的 Android DSL 指南

与 Android 上的 DSL 指南 - 基本自动化操作中所述的自动化操作相比，自动化 DSL 可用于创建更复杂的自动化操作。

包含多项操作的顺序执行

自动化操作可以执行多项操作。例如，您可以拥有多个 action 节点，而不是单个 action 节点，这些节点按顺序运行：

automation {
  sequential {
    starter<_>(...)
    condition {...}
    action {...}
    action {...}
    action {...}
    }
}

包含多项并行操作的顺序执行

如果您在 parallel 节点中放置多个 action 节点，这些操作会同时执行。

automation {
  sequential {
    starter<_>(...)
    condition {...}
    parallel {
      action {...}
      action {...}
      action {...}
    }
  }
}

如果 sequential 节点中有 action 节点位于 parallel 节点之后，这些节点会等待，直到 parallel 节点中的所有节点都执行完毕后才会执行。

延迟

您可以使用 delayFor 关键字在自动化操作中引入暂停，该关键字接受一个 java.time.Duration 实参，表示在继续执行之前暂停的时间。暂停时间可以短至 5 秒，也可以长达 24 小时。

例如，如需切换灯光 4 次，每次切换之间暂停 5 秒，请执行以下操作：

sequential {
  action(light, OnOffLightDevice) { command(OnOff.toggle()) }
  delayFor(Duration.ofSeconds(5))
  action(light, OnOffLightDevice) { command(OnOff.toggle()) }
  delayFor(Duration.ofSeconds(5))
  action(light, OnOffLightDevice) { command(OnOff.toggle()) }
  delayFor(Duration.ofSeconds(5))
  action(light, OnOffLightDevice) { command(OnOff.toggle()) }
}

触发器抑制

触发器抑制是一种功能，可让自动化操作在初始触发事件发生后的一段时间内忽略 starter。例如，如果自动化操作有一个由移动侦测触发的 starter，并且您指定了 5 分钟的触发器抑制时长，那么当 starter 触发时，它在接下来的 5 分钟内不会再次触发。这样可以防止自动化操作快速重复触发。

如需对自动化操作应用触发器抑制，请使用 suppressFor 关键字，并使用 java.time.Duration 实参来表示在响应后续触发器之前等待的时间。 抑制时间可以短至 5 秒，也可以长达 24 小时。

automation {
  sequential {
    val starterNode = starter<_>(device, OccupancySensor, MotionDetection)
    suppressFor(Duration.ofMinutes(30))
    action(light, OnOffLightDevice) { command(OnOff.toggle()) }
}

请注意，触发器抑制会影响自动化操作中位于 suppressFor 之前的所有 starters。

限制执行次数

您可以限制自动化操作的运行次数。

例如，您可能想要设置一个一次性自动化操作，让它在您白天不在家时运行吸尘器。

为此，请设置自动化操作的 maxExecutionCount 元数据字段。 以下示例是一个只能执行一次的自动化操作：

automation {
  // The automation can only be executed once.
  maxExecutionCount = 1
  // When the door lock state changes
  sequential {
    val doorLockEvent = starter<_>(doorLock, DoorLockDevice, LockOperationEvent)
    // if the door is unlocked
    condition() {
      expression = (doorLockEvent.lockOperationType equals LockOperationTypeEnum.Unlock)
    }
    // turn the light on
    action(light, DimmableLightDevice) { command(OnOff.on()) }
  }
}

自动化操作在最后一次执行完毕并达到 maxExecutionCount 后，系统会立即将其删除。自动化操作的历史记录条目仍会保留 在 Google Home app (GHA) 活动 标签页中，包括 automation_id。

在操作中设置特征属性

如需设置特征属性的值，请执行以下操作：

1. 在 action 节点中创建一个 update 节点，并将相关特征作为 update 节点的实参：

   action(deviceReference, deviceType) {
     update(trait) {
   
     }
   }

2. 在 update 节点中，对于要修改的每个属性， 使用 mutator 函数，并向其传递新值。 如需构成 mutator 函数的名称，请执行以下操作：
   1. 将属性的名称大写
   2. 在前面加上单词 set。
   例如，如需更新名为 defaultMoveRate 的属性， 您可以使用名为 setDefaultMoveRate 的 mutator 函数。

请注意，update 节点可以有多个 mutator 函数。以下示例展示了如何更新两个属性：

action(device, Fan) {
  update(FanControl) {
    setPercentSetting(50u)
    setRockSetting(FanControlCluster.RockBitmap.rockUpDown)
  }
}