脚本组件

ESPHome 的 script 组件允许你在一个中心位置定义一系列步骤（操作）。然后你可以在设备配置中几乎任何位置通过单个调用执行该脚本。

# 示例配置条目
script:
  - id: my_script
    then:
      - switch.turn_on: my_switch
      - delay: 1s
      - switch.turn_off: my_switch

配置变量

id (必选, ID): 脚本的 ID。使用此 ID 通过脚本操作与脚本交互。
mode (可选, string): 控制当脚本在先前一次或多次调用仍在运行时被再次调用会发生什么。默认为 single。
- single ：不启动新的运行。发出警告。
- restart ：先停止之前的运行，然后启动新的运行。
- queued ：在之前的运行完成后启动新的运行。默认情况下，最多允许 5 个总计实例（1 个运行中 + 4 个排队）。达到限制时，额外的调用将被拒绝并发出警告。
- parallel ：与之前的运行并行启动一个新的独立运行。
max_runs (可选, int): 允许限制脚本实例的最大数量。
- 对于 queued 模式：指定最大总计实例数（包括运行中的那个）。默认为 5（1 个运行中 + 4 个排队）。有效范围：1-100。
- 对于 parallel 模式：指定最大并行实例数。默认为 0（无限）。有效范围：0-100。
```
script:
  - id: my_script
    mode: queued
    max_runs: 10  # 最多允许 10 个总计实例（1 个运行中 + 9 个排队）
    then:
      - logger.log: "Processing..."
```
parameters (可选, 脚本参数): 脚本可以定义一个或多个参数，执行时需要提供这些参数。这里定义的所有参数都是必需的，调用脚本时必须给出。
then (必选, Action): 要执行的操作。

脚本参数

脚本可以带参数定义。调用脚本时给出的参数可以在脚本的 lambda 操作中使用。要定义参数，请在 parameters: 键下添加参数名称，并为该参数指定数据类型。

支持的数据类型：

bool ：布尔值 true/false。C++ 类型：bool
int ：整数。C++ 类型：int32_t
float ：浮点数。C++ 类型：float
string ：字符串。C++ 类型：std::string

这些类型也都有数组形式：

bool[] ：布尔值数组。C++ 类型：std::vector<bool>
其他类型也类似。

script:
  - id: blink_light
    parameters:
      delay_ms: int
    then:
      - light.turn_on: status_light
      # 参数 delay_ms 可以使用 lambda 访问
      - delay: !lambda return delay_ms;
      - light.turn_off: status_light

`script.execute` 操作

此操作执行脚本。脚本的 mode 决定如果脚本已经在运行会发生什么。

# 在一个触发器中：
on_...:
  then:
    - script.execute: my_script

    # 在 lambda 中调用一个无参数脚本
    - lambda: id(my_script).execute();

    # 带参数调用脚本
    - script.execute:
        id: blink_light
        delay_ms: 500

    # 在 lambda 中调用带参数的脚本
    - lambda: id(blink_light)->execute(1000);

`script.stop` 操作

此操作允许你在执行期间停止给定的脚本。如果脚本没有在运行，则不做任何事。当你想停止一个包含 delay 操作、wait_until 操作或在 while 循环内等内容的脚本时，这很有用。你也可以从脚本自身调用此操作，之后任何后续操作都不会被执行。

# 示例配置条目
script:
  - id: my_script
    then:
      - switch.turn_on: my_switch
      - delay: 1s
      - switch.turn_off: my_switch

# 在一个触发器中：
on_...:
  then:
    - script.stop: my_script

…或作为 lambda：

lambda: 'id(my_script).stop();'

`script.wait` 操作

此操作挂起自动化的执行，直到脚本执行完毕。

注意：如果没有脚本在执行，此操作将立即继续。如果脚本的多个实例在并行运行，此操作将阻塞，直到它们全部终止。

# 示例配置条目
script:
  - id: my_script
    then:
      - switch.turn_on: my_switch
      - delay: 1s
      - switch.turn_off: my_switch

# 在一个触发器中：
on_...:
  then:
    - script.execute: my_script
    - script.wait: my_script

这不能在 lambda 中使用，因为它会阻塞设备的所有功能。脚本甚至都无法运行。

`script.is_running` 条件

此条件允许你检查给定的脚本是否正在运行。如果脚本以 parallel 方式运行，此条件只告诉你给定 id 的至少一个脚本是否在运行，而不是有多少个。不适合与 while 一起使用；请改用 script.wait。

on_...:
  if:
    condition:
      - script.is_running: my_script
    then:
      - logger.log: Script is running!

…或作为 lambda：

lambda: |-
    if (id(my_script).is_running()) {
        ESP_LOGI("main", "Script is running!");
    }

脚本组件

配置变量

脚本参数

script.execute 操作

script.stop 操作

script.wait 操作

script.is_running 条件

另请参阅

`script.execute` 操作

`script.stop` 操作

`script.wait` 操作

`script.is_running` 条件