日期时间组件

ESPHome 支持创建日期时间实体的组件。日期时间实体目前表示可以由用户/前端设置的日期。

NOTE

需要 Home Assistant 2024.4 或更新版本。

基本日期时间配置

ESPHome 中的所有日期时间都有一个名称和可选的图标。

# 示例日期时间配置
name: 检查日期

# 可选变量：
icon: "mdi:calendar-alert"

配置变量：

id (可选, string)：手动指定用于代码生成的 ID。必须指定 id 和 name 中的至少一个。
name (可选, string)：日期时间的名称。必须指定 id 和 name 中的至少一个。

NOTE

如果您为设备设置了 friendly_name，并且希望日期时间使用该名称，可以设置 name: None。

icon (可选, icon)：手动设置前端中日期时间使用的图标。
internal (可选, boolean)：将此组件标记为内部组件。内部组件不会暴露给前端（如 Home Assistant）。仅指定 id 而不指定 name 会隐式将此设置为 true。
disabled_by_default (可选, boolean)：如果为 true，则此实体不应添加到任何客户端的前端（通常是 Home Assistant），除非用户手动启用（通过 Home Assistant UI）。默认为 false。
entity_category (可选, string)：实体的类别。请参阅 https://developers.home-assistant.io/docs/core/entity/#generic-properties 获取可用选项列表。设置为 "" 可移除默认实体类别。
time_id (可选, ID)：时间实体的 ID。如果只定义了一个时间组件，则自动设置为该时间组件的 ID。如果使用 on_time 则为必需。
如果启用了 Webserver 并选择了版本 3，则支持 Webserver 组件的所有其他选项。请参阅 Webserver 版本 3。

MQTT 选项：

MQTT 组件的所有其他选项。

时间和日期时间选项：

on_time (可选, 自动化)：当前日期时间或时间与当前状态匹配时运行的自动化。仅在 time 或 datetime 类型上有效。使用 on_time 会导致 time_id 成为必需，如果配置中存在时间源，time_id 将自动分配，如果没有配置时间，则会导致配置无效。

自动化

您可以通过 id(datetime_id).state_as_esptime() 访问最新状态作为 ESPTime 对象

`on_value`

当发布新值时将触发此自动化。在 Lambda 中，您可以从触发器中获取作为 ESPTime 对象的值，使用 x。

datetime:
  - platform: template
    # ...
    on_value:
      then:
        - lambda: |-
            if(x.hour >= 12) {
              ESP_LOGD("main", "更新的小时晚于或等于 12");
            } else {
              ESP_LOGD("main", "更新的小时早于 12");
            }

配置变量：请参阅自动化。

日期自动化

`datetime.date.set` 动作

这是一个用于设置日期时间日期状态的动作。提供的 date 可以是以下 3 种格式之一：

# 字符串日期
- datetime.date.set:
    id: my_datetime_date
    date: "2023-12-04"

# 单独的日期部分
- datetime.date.set:
    id: my_datetime_date
    date:
      year: 2023
      month: 12
      day: 4

# 使用 lambda
- datetime.date.set:
    id: my_datetime_date
    date: !lambda |-
      // 返回 ESPTime 结构体
      return {.day_of_month = 4, .month = 12, .year = 2023};

配置变量：

id (必填, ID)：要设置的日期时间的 ID。
date (必填, string, 日期部分, 可模板化)：要将日期时间设置为的值。

lambda 调用

在 lambda 中，您可以调用所有日期时间的多种方法来执行一些高级操作（有关更多信息，请参阅完整的 API 参考）。

.make_call()：创建用于更新日期时间值的调用。

    // 在 lambda 中，将日期设置为 2024-02-25
    auto call = id(my_datetime_date).make_call();
    call.set_date("2024-02-25");
    call.perform();

请查看 API 参考，了解 DateCall 对象可用的方法。

.year：检索 date 的当前年份。如果尚未设置值，则为 0。
.month：检索 date 的当前月份。如果尚未设置值，则为 0。
.day：检索 date 的当前日期。如果尚未设置值，则为 0。
.state_as_esptime()：检索日期时间的当前值作为 API Reference: ESPTime 对象。

    // 例如，在接收到值时创建自定义日志消息：
    ESP_LOGI("main", "我的日期时间值：%04d-%02d-%02d", id(my_date).year, id(my_date).month, id(my_date).day);

时间自动化

`datetime.time.set` 动作

这是一个用于设置日期时间时间状态的动作。提供的 time 可以是以下 3 种格式之一：

# 字符串时间
- datetime.time.set:
    id: my_datetime_time
    time: "12:34:56"

# 单独的时间部分
- datetime.time.set:
    id: my_datetime_time
    time:
      hour: 12
      minute: 34
      second: 56

# 使用 lambda
- datetime.time.set:
    id: my_datetime_time
    time: !lambda |-
      // 返回 ESPTime 结构体
      return {.second = 56, .minute = 34, .hour = 12};

配置变量：

id (必填, ID)：要设置的日期时间的 ID。
time (必填, string, 时间部分, 可模板化)：要将日期时间设置为的值。

lambda 调用

在 lambda 中，您可以调用所有日期时间的多种方法来执行一些高级操作（有关更多信息，请参阅完整的 API 参考）。

.make_call()：创建用于更新日期时间值的调用。

    // 在 lambda 中，将时间设置为 12:34:56
    auto call = id(my_datetime_time).make_call();
    call.set_time("12:34:56");
    call.perform();

请查看 API 参考，了解 TimeCall 对象可用的方法。

.hour：检索 time 的当前小时。如果尚未设置值，则为 0。
.minute：检索 time 的当前分钟。如果尚未设置值，则为 0。
.second：检索 time 的当前秒。如果尚未设置值，则为 0。
.state_as_esptime()：检索日期时间的当前值作为 API Reference: ESPTime 对象。

    // 例如，在接收到值时创建自定义日志消息：
    ESP_LOGI("main", "我的日期时间值：%0d:%02d:%02d", id(my_datetime_time).hour, id(my_datetime_time).minute, id(my_datetime_time).second);

日期时间自动化

`datetime.datetime.set` 动作

这是一个用于设置日期时间日期时间状态的动作。提供的 datetime 可以是以下 3 种格式之一：

# 字符串日期时间
- datetime.time.set:
    id: my_datetime
    datetime: "2024-12-31 12:34:56"

# 单独的日期时间部分
- datetime.datetime.set:
    id: my_datetime
    datetime:
      year: 2024
      month: 12
      day: 31
      hour: 12
      minute: 34
      second: 56

# 使用 lambda
- datetime.datetime.set:
    id: my_datetime
    datetime: !lambda |-
      // 返回 ESPTime 结构体
      return {.second = 56, .minute = 34, .hour = 12, .day_of_month = 31, .month = 12, .year = 2024};

配置变量：

id (必填, ID)：要设置的日期时间的 ID。
datetime (必填, string, 日期时间部分, 可模板化)：要将日期时间设置为的值。

Lambda 调用

对于更复杂的用例，可以从 lambda 内部使用日期时间的多种方法。有关更多信息，请参阅完整的 API 参考。

.make_call()：创建用于更新日期时间值的调用。

    // 在 lambda 中，将日期时间设置为 2024-12-31 12:34:56
    auto call = id(my_datetime).make_call();
    call.set_datetime("2024-12-31 12:34:56");
    call.perform();

请查看 API 参考，了解 DateTimeCall 对象可用的方法。

.year：检索 datetime 的当前年份。如果尚未设置值，则为 0。
.month：检索 datetime 的当前月份。如果尚未设置值，则为 0。
.day：检索 datetime 的当前日期。如果尚未设置值，则为 0。
.hour：检索 datetime 的当前小时。如果尚未设置值，则为 0。
.minute：检索 datetime 的当前分钟。如果尚未设置值，则为 0。
.second：检索 datetime 的当前秒。如果尚未设置值，则为 0。
.state_as_esptime()：检索日期时间的当前值作为 API Reference: ESPTime 对象。

    // 例如，在接收到值时创建自定义日志消息：
    ESP_LOGI("main", "我的日期时间值：%04d-%02d-%02d %0d:%02d:%02d",
             id(my_datetime).year, id(my_datetime).month, id(my_datetime).day,
             id(my_datetime).hour, id(my_datetime).minute, id(my_datetime).second);

日期时间组件

基本日期时间配置

自动化

on_value

日期自动化

datetime.date.set 动作

lambda 调用

时间自动化

datetime.time.set 动作

lambda 调用

日期时间自动化

datetime.datetime.set 动作

Lambda 调用

另请参阅

`on_value`

`datetime.date.set` 动作

`datetime.time.set` 动作

`datetime.datetime.set` 动作