时间格式本地化 Cluster（TimeFormatLocalization）

Cluster ID: 0x002C  |  所在 Endpoint: Endpoint 0（Root） |  角色: Server（通过 Write 属性配置，无命令）

TimeFormatLocalization 控制设备上的时间和日期显示格式偏好。 它不负责时间本身的获取或同步（那是 TimeSynchronization Cluster 的工作）， 而是决定设备在屏幕、面板等界面上怎么展示时间 —— 用 12 小时制还是 24 小时制，用公历还是其他日历。

这个 Cluster 非常精简 —— 最少只有 1 个属性（HourFormat）， 支持 CALFMT Feature 时再增加 2 个日历相关属性。没有任何命令，所有配置都通过直接写属性完成。

Feature 位图

TimeFormatLocalization 通过 FeatureMap（0xFFFC）声明设备是否支持日历格式配置：

属性总览

TimeFormatLocalization 最多有 3 个属性，其中 2 个依赖 CALFMT Feature。点击属性 ID 可跳转到详细说明。

HourFormat（时间显示格式）

控制设备以 12 小时制还是 24 小时制显示时间。这是 TimeFormatLocalization 唯一的必须属性， 所有支持此 Cluster 的设备都必须实现。可读可写，直接写属性即可切换。

HourFormatEnum 枚举值

写属性示例（切换为 12 小时制）：

// App → Device：将时间显示切换为 12 小时制
{
  "writeRequests": [{
    "attributePath": {
      "endpointId": 0,
      "clusterId": "0x002C",
      "attributeId": "0x00"        // HourFormat
    },
    "data": 0                      // 12hr
  }]
}

↑ 返回属性列表

ActiveCalendarType（当前日历类型）

控制设备使用哪种日历系统来显示日期。可读可写，但只能写入 SupportedCalendarTypes 列表中包含的值。 需要设备支持 CALFMT Feature，否则此属性不存在。

CalendarTypeEnum 枚举值

写属性示例（切换为中国农历）：

// App → Device：将日历切换为中国农历
{
  "writeRequests": [{
    "attributePath": {
      "endpointId": 0,
      "clusterId": "0x002C",
      "attributeId": "0x01"        // ActiveCalendarType
    },
    "data": 1                      // Chinese（中国农历）
  }]
}

↑ 返回属性列表

SupportedCalendarTypes（支持的日历列表）

只读属性，返回设备支持的所有日历类型列表。列表中的每个元素都是 CalendarTypeEnum 的一个值。 App 应该用这个列表来构建日历选择的 UI —— 只展示设备实际支持的选项。 需要设备支持 CALFMT Feature。

↑ 返回属性列表

示例数据

读取一台支持 CALFMT Feature 的智能恒温器的 TimeFormatLocalization 属性：

{
  // --- 时间格式 ---
  "0x00": 1,              // HourFormat = 24hr（24 小时制）

  // --- 日历格式（需 CALFMT Feature）---
  "0x01": 4,              // ActiveCalendarType = Gregorian（公历）
  "0x02": [4, 0, 1]       // SupportedCalendarTypes = [Gregorian, Buddhist, Chinese]
}

常见场景