脚本组件

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

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

配置变量

id (Required, ID): 脚本的 ID。使用此 ID 通过脚本动作与脚本交互。
mode (Optional, string): 控制当脚本从一个或多个先前的调用仍在运行时被调用时会发生什么。默认为 single。
- single: 不开始新的运行。发出警告。
- restart: 先停止先前的运行，然后开始新的运行。
- queued: 在先前的运行完成后开始新的运行。默认情况下，最多允许 5 个总实例（1 个运行 + 4 个排队）。当达到限制时，额外的调用将被拒绝并发出警告。
- parallel: 与先前的运行并行开始新的独立运行。
max_runs (Optional, 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: "处理中..."
```
parameters (Optional, 脚本参数): 脚本可以定义一个或多个必须在执行时提供的参数。此处定义的所有参数都是必需的，调用脚本时必须给出。
then (Required, 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` 动作

此动作执行脚本。脚本模式决定如果脚本已在运行会发生什么。

# 在触发器中：
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: 脚本正在运行！

…或作为 lambda：

lambda: |-
    if (id(my_script).is_running()) {
        ESP_LOGI("main", "脚本正在运行！");
    }

脚本组件

配置变量

脚本参数

script.execute 动作

script.stop 动作

script.wait 动作

script.is_running 条件

另见

`script.execute` 动作

`script.stop` 动作

`script.wait` 动作

`script.is_running` 条件