罩盖组件

cover 组件是 ESPHome 中罩盖的通用表示。 罩盖当前可以处于关闭或开启状态，并支持三种类型的 命令：开启、关闭和停止。

基础罩盖配置

所有罩盖配置模式都继承自此模式——你可以为罩盖设置这些键。

cover:
  - platform: ...
    device_class: garage

配置变量：

• id (可选，字符串)：手动指定用于代码生成的 ID。id 和 name 至少指定一个。
• name (可选，字符串)：罩盖的名称。id 和 name 至少指定一个。

NOTE

如果你的设备设置了 friendly_name，并且 你希望罩盖使用该名称，可以设置 name: None。

• device_class (可选，字符串)：该 传感器的设备类别。可用选项列表请参见 https://www.home-assistant.io/integrations/cover/#device-class。

• icon (可选，图标)：手动设置罩盖在前端中使用的图标。

高级选项：

• internal (可选，布尔值)：将该组件标记为内部组件。内部组件不会 暴露给前端（如 Home Assistant）。仅指定 id 而不指定 name 会隐式地将此项设为 true。

• disabled_by_default (可选，布尔值)：如果为 true，则除非用户手动启用此实体（通过 Home Assistant UI）， 否则不应将该实体添加到任何客户端的前端中（通常是 Home Assistant）。 默认为 false。

• entity_category (可选，字符串)：实体的类别。 可用选项列表请参见 https://developers.home-assistant.io/docs/core/entity/#generic-properties 设置为 "" 以移除默认的实体类别。

• 如果启用了 Webserver 且选择了版本 3，则包含 Webserver 组件的所有其他选项。请参见 Webserver 版本 3。

MQTT 选项：

• mqtt_json_state_payload (可选，布尔值)：设为 true 时，状态变更将 仅作为单个 JSON 对象发布到 state_topic，每次状态变更一条。示例：

  { "state": "open", "position": 100, "tilt": 50 }

  设为 false 时，各个值将分别发布到 state_topic、position_state_topic 和 tilt_state_topic。默认为 false。

• position_state_topic (可选，字符串)：用于发布 罩盖位置变更的主题。如果 mqtt_json_state_payload 设为 true，则此项无效。

• position_command_topic (可选，字符串)：用于接收 罩盖位置命令的主题。

• tilt_state_topic (可选，字符串)：用于发布罩盖 倾斜状态变更的主题。如果 mqtt_json_state_payload 设为 true，则此项无效。

• tilt_command_topic (可选，字符串)：用于接收 罩盖倾斜命令的主题。

• MQTT 组件 中的所有其他选项。

动作

cover.open 动作

此动作在执行时打开具有给定 ID 的罩盖。

on_...:
  then:
    - cover.open: cover_1

NOTE

此动作也可以在 lambdas 中表示：

auto call = id(cover_1).make_call();
call.set_command_open();
call.perform();

cover.close 动作

此动作在执行时关闭具有给定 ID 的罩盖。

on_...:
  then:
    - cover.close: cover_1

NOTE

此动作也可以在 lambdas 中表示：

auto call = id(cover_1).make_call();
call.set_command_close();
call.perform();

cover.stop 动作

此动作在执行时停止具有给定 ID 的罩盖。

on_...:
  then:
    - cover.stop: cover_1

NOTE

此动作也可以在 lambdas 中表示：

auto call = id(cover_1).make_call();
call.set_command_stop();
call.perform();

cover.toggle 动作

此动作在执行时切换具有给定 ID 的罩盖， 在关闭/停止/开启/停止等状态之间循环。这允许通过单个按钮控制 罩盖。

on_...:
  then:
    - cover.toggle: cover_1

NOTE

此动作也可以在 lambdas 中表示：

auto call = id(cover_1).make_call();
call.set_command_toggle();
call.perform();

cover.control 动作

此动作是其他罩盖动作的更通用版本， 允许设置所有罩盖属性。

on_...:
  then:
    - cover.control:
        id: cover_1
        position: 50%
        tilt: 50%

配置变量：

• id (必填，ID)：要控制的罩盖。

• stop (可选，布尔值，可模板化)：是否停止罩盖。

• state (可选，字符串，可模板化)：将罩盖设置到的状态——OPEN 或 CLOSE 之一。

• position (可选，浮点数，可模板化)：要设置的罩盖位置。

  • 0.0 = 0% = CLOSED
  • 1.0 = 100% = OPEN

• tilt (可选，浮点数，可模板化)：要设置的倾斜位置。范围为 0% 至 100%。

NOTE

此动作也可以在 lambdas 中表示：

auto call = id(cover_1).make_call();
// 设置属性
call.set_position(0.5);
call.perform();

条件

cover.is_open 条件

此条件检查具有给定 ID 的罩盖是否完全开启。

on_...:
  if:
    condition:
      cover.is_open: cover_1
    then:
      - logger.log: "Cover is open!"

配置变量：

• id (必填，ID)：要检查的罩盖。

cover.is_closed 条件

此条件检查具有给定 ID 的罩盖是否完全关闭。

on_...:
  if:
    condition:
      cover.is_closed: cover_1
    then:
      - logger.log: "Cover is closed!"

配置变量：

• id (必填，ID)：要检查的罩盖。

触发器

cover.on_opened 触发器

此触发器在罩盖每次达到完全开启状态时激活。

cover:
  - platform: template  # 或任何其他平台
    # ...
    on_opened:
      - logger.log: "Cover is fully open!"

cover.on_closed 触发器

此触发器在罩盖每次达到完全关闭状态时激活。

cover:
  - platform: template  # 或任何其他平台
    # ...
    on_closed:
      - logger.log: "Cover is fully closed!"

cover.on_opening 触发器

此触发器在罩盖每次开始开启时激活。

cover:
  - platform: template  # 或任何其他平台
    # ...
    on_opening:
      - logger.log: "Cover started opening"

cover.on_closing 触发器

此触发器在罩盖每次开始关闭时激活。

cover:
  - platform: template  # 或任何其他平台
    # ...
    on_closing:
      - logger.log: "Cover started closing"

cover.on_idle 触发器

此触发器在罩盖每次停止移动并进入空闲状态时激活。

cover:
  - platform: template  # 或任何其他平台
    # ...
    on_idle:
      - logger.log: "Cover stopped moving"

NOTE

on_open 触发器已弃用，将在未来版本中移除。请改用 on_opened。

Lambdas

在 lambdas 中，可以获取罩盖的当前状态（注意这些 字段是只读的，如果你想对罩盖进行操作，请使用上面所示的 make_call() 方法）。

• position : 获取罩盖的当前位置，值为 0.0（关闭）到 1.0（开启）之间的数值。

        if (id(my_cover).position == COVER_OPEN) {
          // 罩盖开启
        } else if (id(my_cover).position == COVER_CLOSED) {
          // 罩盖关闭
        } else {
          // 罩盖处于开启和关闭之间
        }

• tilt : 获取罩盖的当前倾斜位置，值为 0.0 到 1.0 之间的数值。

• current_operation : 罩盖当前正在执行的操作：

        if (id(my_cover).current_operation == CoverOperation::COVER_OPERATION_IDLE) {
          // 罩盖处于空闲状态
        } else if (id(my_cover).current_operation == CoverOperation::COVER_OPERATION_OPENING) {
          // 罩盖当前正在开启
        } else if (id(my_cover).current_operation == CoverOperation::COVER_OPERATION_CLOSING) {
          // 罩盖当前正在关闭
        }

另请参见

• API 参考：Cover
• API 参考：cover.h