日期时间组件

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

NOTE

需要 Home Assistant 2024.4 或更高版本。

基础日期时间配置

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

# Example datetime configuration
name: Date to check

# Optional variables:
icon: "mdi:calendar-alert"

配置变量：

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

NOTE

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

icon (可选, icon): 手动设置在前端中为日期时间使用的图标。
internal (可选, boolean): 将此组件标记为内部组件。内部组件将不会暴露给前端（如 Home Assistant）。仅指定不带 name 的 id 将隐式地将此设置为 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 Version 3。

MQTT 选项：

还包括 MQTT 组件的所有其他选项。

时间和日期时间选项：

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

自动化

您可以通过 id(datetime_id).state_as_esptime() 以 ESPTime 对象的形式访问最新状态。

`on_value`

当发布新值时，将触发此自动化。在 Lambdas 中，您可以通过 x 从触发器中以 ESPTime 对象的形式获取值。

datetime:
  - platform: template
    # ...
    on_value:
      then:
        - lambda: |-
            if(x.hour >= 12) {
              ESP_LOGD("main", "Updated hour is later or equal to 12");
            } else {
              ESP_LOGD("main", "Updated hour is earlier than 12");
            }

配置变量：请参阅 Automation。

日期自动化

`datetime.date.set` 操作

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

# String date
- datetime.date.set:
    id: my_datetime_date
    date: "2023-12-04"

# Individual date parts
- datetime.date.set:
    id: my_datetime_date
    date:
      year: 2023
      month: 12
      day: 4

# Using a lambda
- datetime.date.set:
    id: my_datetime_date
    date: !lambda |-
      // Return an ESPTime struct
      return {.day_of_month = 4, .month = 12, .year = 2023};

配置变量：

id (必填, ID): 要设置的日期时间的 ID。
date (必填, string, 日期部分, templatable): 要设置为日期时间的值。

lambda 调用

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

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

    // Within lambda, set the date to 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 参考：ESPTime 对象的形式检索日期时间的当前值。

    // For example, create a custom log message when a value is received:
    ESP_LOGI("main", "Value of my datetime: %04d-%02d-%02d", id(my_date).year, id(my_date).month, id(my_date).day);

时间自动化

`datetime.time.set` 操作

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

# String time
- datetime.time.set:
    id: my_datetime_time
    time: "12:34:56"

# Individual time parts
- datetime.time.set:
    id: my_datetime_time
    time:
      hour: 12
      minute: 34
      second: 56

# Using a lambda
- datetime.time.set:
    id: my_datetime_time
    time: !lambda |-
      // Return an ESPTime struct
      return {.second = 56, .minute = 34, .hour = 12};

配置变量：

id (必填, ID): 要设置的日期时间的 ID。
time (必填, string, 时间部分, templatable): 要设置为日期时间的值。

lambda 调用

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

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

    // Within lambda, set the time to 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 参考：ESPTime 对象的形式检索日期时间的当前值。

    // For example, create a custom log message when a value is received:
    ESP_LOGI("main", "Value of my datetime: %0d:%02d:%02d", id(my_datetime_time).hour, id(my_datetime_time).minute, id(my_datetime_time).second);

日期时间自动化

`datetime.datetime.set` 操作

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

# String datetime
- datetime.time.set:
    id: my_datetime
    datetime: "2024-12-31 12:34:56"

# Individual datetime parts
- datetime.datetime.set:
    id: my_datetime
    datetime:
      year: 2024
      month: 12
      day: 31
      hour: 12
      minute: 34
      second: 56

# Using a lambda
- datetime.datetime.set:
    id: my_datetime
    datetime: !lambda |-
      // Return an ESPTime struct
      return {.second = 56, .minute = 34, .hour = 12, .day_of_month = 31, .month = 12, .year = 2024};

配置变量：

id (必填, ID): 要设置的日期时间的 ID。
datetime (必填, string, 日期时间部分, templatable): 要设置为日期时间的值。

Lambda 调用

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

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

    // Within lambda, set the datetime to 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 参考：ESPTime 对象的形式检索日期时间的当前值。

    // For example, create a custom log message when a value is received:
    ESP_LOGI("main", "Value of my datetime: %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` 操作