2025.3.4
首页 ▸ Integrations ▸

脚本

脚本集成允许用户指定一系列由 Home Assistant 执行的操作。当你启动脚本时，这些操作会被执行。脚本集成将为每个脚本创建一个实体，并允许通过操作进行控制。

可以通过 YAML 配置（如下所述）或通过 用户界面 创建脚本。

配置

操作的顺序使用 Home Assistant 脚本语法 指定。

# 示例 configuration.yaml 条目
script:
  message_temperature:
    sequence:
      # 这是 Home Assistant 脚本语法
      - action: notify.notify
        data:
          message: "当前温度是 {{ states('sensor.temperature') }}"

Important

脚本名称（例如，上述示例中的 message_temperature）不得包含大写字母或连字符（减号）字符，即 -。为更好的可读性，建议使用下划线（_）字符来分隔单词。

Configuration Variables

Looking for your configuration file?
alias string (Optional)

脚本的友好名称。

icon string (Optional)

脚本的图标。

description string (Optional)

将在 开发者工具 下 操作 选项卡中显示的脚本描述。

variables map (Optional, default: {})

在模板中可用的变量

PARAMETER_NAME any

变量的值。任何 YAML 都是有效的。模板也可以用来传递值给变量。

fields map (Optional, default: {})

关于脚本字段参数的信息；请参见下面的 传递变量给脚本 部分。

FIELD_NAME map

此脚本使用的参数字段。所有子选项仅用于在 UI 中创建此脚本的表示。

name string

此脚本参数字段的名称。

description string

此脚本参数的描述。

advanced boolean

将此字段标记为高级参数。仅当用户启用高级模式时，此字段才会显示在 UI 中。

required boolean

标记此字段是否是必需的。此功能仅限于 UI。

example string

示例值。这将仅在 开发者工具 的 操作 选项卡中提供的选项表中显示。

default any

此字段的默认值，如 UI 中所示。

selector selector (Optional)

用于此输入的 选择器。选择器定义了输入在前端 UI 中的显示方式。

mode string (Optional, default: single)

控制脚本在仍然运行之前一个或多个调用时的行为。请参见 脚本模式。

max integer (Optional, default: 10)

控制一次执行和/或排队上限的最大运行次数。仅在 queued 和 parallel 模式下有效。

max_exceeded string (Optional, default: warning)

当 max 超过（对于 single 模式实际上是 1）时，将发出日志消息以指示发生了这种情况。此选项控制该日志消息的严重级别。有关有效选项的列表，请参见 日志级别。可以指定为 silent 以 suppress 消息不被发出。

sequence list Required

脚本中要执行的操作顺序。

脚本模式

模式 描述
single 不启动新运行。发出警告。
restart 在停止前一个运行后启动新运行。
queued 在所有先前运行完成后启动新运行。运行保证按照排队顺序执行。
parallel 启动一个与先前运行并行的新独立运行。

传递变量给脚本

作为操作的一部分，变量可以传递给脚本，以便它们在该脚本的模板中可用。

要配置脚本以接受使用 UI 的变量，可以将变量作为字段添加到脚本编辑器。

  1. 在脚本编辑器中，在三点菜单中选择 添加字段。
  2. 在基本信息和 序列 部分之间添加一个名为 字段 的新部分。
  3. 输入名称并选择每个所需字段的类型和选项。
  4. 在此设置的字段将在其他 UI 编辑器中显示，例如在一个调用脚本的自动化中，作为输入根据字段类型。
  5. 要使用字段数据，请在它们被添加时使用 字段键名称 作为模板，如下例所示。

在脚本中使用变量需要使用模板：

# 示例配置.yaml 条目
script:
  notify_pushover:
    description: "发送 pushover 通知"
    fields:
      title:
        description: "通知的标题"
        example: "状态变化"
      message:
        description: "消息内容"
        example: "灯是开着的!"
    sequence:
      - condition: state
        entity_id: switch.pushover_notifications
        state: "on"
      - action: notify.pushover
        data:
          title: "{{ title }}"
          message: "{{ message }}"

除了自动化编辑器 UI，可以在操作数据中将变量传递给脚本。这可以通过直接调用脚本或者通用的 script.turn_on 操作使用。区别在于 等待脚本完成 中有所描述。所有操作数据都将在模板中作为变量提供，即使没有在脚本中指定为字段。此示例展示了如何直接调用脚本：

# 示例配置.yaml 条目
automation:
  triggers:
    - trigger: state
      entity_id: light.bedroom
      from: "off"
      to: "on"
  actions:
    - action: script.notify_pushover
      data:
        title: "状态变化"
        message: "灯是开着的!"

此示例展示了使用 script.turn_on 操作：

# 示例配置.yaml 条目
automation:
  triggers:
    - trigger: state
      entity_id: light.bedroom
      from: "off"
      to: "on"
  actions:
    - action: script.turn_on
      target:
        entity_id: script.notify_pushover
      data:
        variables:
          title: "状态变化"
          message: "灯是开着的!"

Note

可以被模板使用的脚本变量包括以下内容：

  • 从配置中作为字段提供的变量

  • 在从操作启动时传递的数据变量，

  • this 变量，其值是当前脚本状态的字典。

等待脚本完成

在“直接”调用脚本（例如 script.NAME）时，调用脚本将等待被调用脚本完成。 如果发生任何导致被调用脚本中断的错误，调用脚本也将中断。

通过 script.turn_on 操作调用脚本（或多个脚本）时，调用脚本 不会 等待。它按列出顺序启动脚本，并在最后一个脚本启动后立即继续。 在被调用脚本中发生的导致它们中断的任何错误 不会 影响调用脚本。

以下是调用脚本不等待的示例。它在被调用脚本“后台”运行时执行其他操作。然后通过 wait_template 等待被调用脚本完成。 这种技术也可以用于调用脚本等待被调用脚