Android DSL 概念

本文將概述 Android 自動化 DSL 的基本概念。

自動化元件

自動化作業包含下列基本元件，通常會依此順序評估：

1. 啟動條件：定義啟動自動化動作的初始條件，例如特徵的變更。自動化動作必須有啟動條件。
2. 條件：自動化功能啟用後，要評估的任何其他限制。條件中的運算式必須評估為 true，自動化動作才能繼續執行。
3. 動作：所有條件都符合時執行的指令或狀態更新。

舉例來說，假設你設定的自動化動作是在日落到日出之間，房間的電視開啟時調暗燈光。在這個例子中：

1. Starter：電視已開啟，這是電視特徵的狀態變更。
2. 條件：系統會評估電視所在住家的目前時間。
3. 動作：調暗電視所在房間的燈光。

當房間的電視開啟時，自動化動作就會啟動，但只有在符合「時間介於日落和日出之間」的條件時，自動化動作才會執行。

除了基本結構外，Home API 中的自動化動作也包含中繼資料，例如 name 和 description，可用於向開發人員和使用者識別自動化動作。

節點

在 Home API 中，自動化動作的邏輯結構由節點組成。 節點是抽象的可重複使用單元，代表實體行為或執行流程。每個節點都可以有輸入變數，以及可能由其他節點使用的輸出變數。

行為節點

啟動條件和動作等節點是行為節點。啟動條件會根據裝置屬性變化啟動自動化動作。動作會發出裝置指令或更新屬性。

行為節點通常會與裝置特徵和輸出特徵狀態繫結，做為其他節點的輸入內容。

執行流程節點

部分節點代表執行流程，例如循序和並行。每個節點都包含定義自動化動作的行為節點。

舉例來說，循序流程可能包含依序執行的節點。通常是啟動條件、限制條件和動作。

平行流程可能同時執行多個動作節點，例如同時開啟多盞燈。並行流程後方的節點會等到並行流程的所有分支完成後，才會執行。

另一種執行流程是條件流程，可根據運算式的評估結果變更執行流程。

舉例來說，您可能有一個自動化動作，會根據是否為夜間執行動作。條件節點會檢查一天中的時間，然後根據評估結果，選擇適當的執行路徑。

如果想使用多個啟動器來啟動自動化動作，選取流程就非常實用。在 select 流程中加入兩個以上的啟動條件時，任一啟動條件都能啟動自動化動作。

舉例來說，你可以編寫自動化動作，在日落時、溫度超過特定門檻時，或亮度超過門檻時，降低百葉窗。這三種情境分別由三個不同的啟動器處理，且這三個啟動器都會包裝在 select 流程中。

巢狀流程

在複雜的自動化程序中，執行流程節點也可以巢狀化。舉例來說，您可能有一個循序流程，會執行平行流程。

您可以根據下表列出的限制，以各種方式巢狀化及合併 DSL 節點，滿足特定需求。「建構工具」欄會連結至 Kotlin 型別安全建構工具說明文件，其中詳述各節點類型允許使用的項目。

自動化 DSL

在 Home API 中，自動化動作是使用 Automation DSL (網域專屬語言) 定義。自動化 DSL 是以 Kotlin DSL (網域特定語言) 實作，使用 Kotlin 型別安全建構工具，專門用於定義自動化範本。

編譯自動化作業時，Kotlin 型別安全建構工具會產生 Kotlin 資料類別，然後序列化為通訊協定緩衝區 JSON，用於呼叫 Google 的自動化服務。

自動化 DSL 可簡化及簡化自動化建構程序。它會原生使用與 Device API 中Matter標準特徵和smart home特徵相同的資料模型。

自動化 DSL 也會根據抽象裝置類型定義自動化邏輯，而非使用者住家中的特定裝置例項。開發人員可藉此提供可在執行階段使用的輸入參數，指定實際裝置例項，以及其他重要參數值。

DSL 語法與 Kotlin 類似，同樣具有類型安全，但以 Automation DSL 編寫的自動化程序，比以純 Kotlin 編寫的相同自動化程序更簡單明瞭。

範例

以下是使用 Automation DSL 編寫的自動化動作範例，可開啟裝置：

val automation = automation {
  name = "MyFirstAutomation"
  description = "If light1 is on, turn on light2."
  isActive = true
  sequential {
    val onOffTrait = starter<_>(device1, OnOffLightDevice, OnOff)
    condition() { expression = onOffTrait.onOff equals true }
    action(device2, OnOffLightDevice) { command(OnOff.on()) }
  }
}

這項自動化動作非常基本：當燈具 (device1) 開啟時 (onOff 屬性變更為 true)，系統會傳送 on() 指令來開啟燈具 (device2)。

自動化程序會使用 sequential 節點，表示節點會依序執行。

sequential 節點內有行為節點，例如 starter、condition 和 action。starter 節點的輸出內容會指派給變數，供 condition 節點使用。