前端智能家居UI组件【免费下载链接】frontend:lollipop: Frontend for Home Assistant项目地址https://gitcode.com/gh_mirrors/frontend149/frontend点击查看免费下载本文围绕 Home Assistant frontend 项目 gallery 中的 Date-Time Format (Numeric) 参考页展开系统讲解formatDateTimeNumeric这一数值日期时间格式化函数的组成原理、语言与时区适配机制并给出可直接复用的调用方式与测试验证依据。读完本文你将掌握该函数如何组合数值日期 时间理解FrontendLocaleData中日期格式、时间格式与时区三个关键维度的作用并能读懂 gallery 中语言 × 12/24 小时制对比矩阵的底层实现。一、参考页与函数的定位在 gallery/src/pages/date-time/date-time-numeric.markdown 中该页面被定义为列出所有支持语言及其可用的日期时间格式对应的格式化函数原型为const formatDateTimeNumeric: (dateObj: Date, locale: FrontendLocaleData) string需要说明的是这是 gallery 文档中简化后的签名。在真实源码中该函数还需要第三个参数config: HassConfig用于解析服务端时区完整签名如下见 src/common/datetime/format_date_time.tsexport const formatDateTimeNumeric ( dateObj: Date, locale: FrontendLocaleData, config: HassConfig ) ${formatDateNumeric(dateObj, locale, config)}, ${formatTime( dateObj, locale, config )};该页面在 gallery 侧边栏中位于 Date and Time 分类下的 Combined 分组与date-time、date-time-seconds、date-time-short、date-time-short-year等页面并列见 gallery/sidebar.js用于集中展示日期 时间组合型格式在各语言下的表现。二、组合原理数值日期 时间从实现可以看出formatDateTimeNumeric的输出由两个独立子格式化器拼接而成中间用逗号加空格分隔formatDateNumeric(dateObj, locale, config)负责产出纯数值日期如11/18/2017、18.11.2017formatTime(dateObj, locale, config)负责产出时间部分如11:12 PM或23:12。最终输出形如12 小时制am_pm11/18/2017, 11:12 PM24 小时制twenty_four11/18/2017, 23:12这两组输出由 test/common/datetime/format_date_time.test.ts 中的单元测试逐字断言是可直接验证的既定行为。三、数值日期部分formatDateNumeric 与日期顺序重排formatDateNumeric定义于 src/common/datetime/format_date.ts是理解数值日期的关键。它根据locale.date_format的取值走两条路径1. 跟随语言或系统language / system当date_format为DateFormat.language或DateFormat.system时直接交由Intl.DateTimeFormat按目标语言system时传入undefined使用浏览器语言格式化输出该语言默认的数值日期写法。例如测试中的德语输出为18.11.2017见 test/common/datetime/format_date.test.ts。2. 显式指定顺序DMY / MDY / YMD当用户显式选择了DateFormat.DMY、DateFormat.MDY或DateFormat.YMD时函数先通过Intl.DateTimeFormat#formatToParts拆出day、month、year以及literal分隔符等各部分再按下表重新拼装枚举值拼装顺序英语示例2017-11-18DateFormat.DMY日-月-年18/11/2017DateFormat.MDY月-日-年11/18/2017DateFormat.YMD年-月-日2017/11/18值得注意的细节函数会提取formatToParts返回的literal部分作为分隔符如/或.并处理尾部多余的 literal同时针对保加利亚语bg在YMD模式下去掉结尾分隔符的特殊逻辑。相关断言同样存在于 test/common/datetime/format_date.test.ts。3. 时区无论走哪条路径formatDateNumericMem都会传入timeZone: resolveTimeZone(locale.time_zone, serverTimeZone)确保日期按用户选择的时区归属计算而不是简单取Date对象的本地时间。四、时间部分formatTime 与 12/24 小时制判定时间部分由formatTimesrc/common/datetime/format_time.ts实现同样基于Intl.DateTimeFormatnew Intl.DateTimeFormat(locale.language, { hour: numeric, minute: 2-digit, hourCycle: useAmPm(locale) ? h12 : h23, timeZone: resolveTimeZone(locale.time_zone, serverTimeZone), })这里最核心的是useAmPm(locale)决定的hourCycle输出h12→ 12 小时制带 AM/PM 标记输出h23→ 24 小时制。useAmPm的实现位于 src/common/datetime/use_am_pm.ts其判定逻辑分为两类显式指定time_format为TimeFormat.am_pm枚举值12时返回true为TimeFormat.twenty_four枚举值24时返回false跟随语言/系统当time_format为language或system时用new Date(January 1, 2023 22:00:00).toLocaleString(testLanguage)做一次探测——若结果字符串包含10意味着 22:00 被渲染为 10 PM 而不是 22:00则判定该语言使用 12 小时制否则使用 24 小时制。这是一个用格式化结果反推显示习惯的巧妙技巧。顺带一提format_date_time.ts中还提供了带秒formatDateTimeWithSeconds、短格式formatShortDateTime、formatShortDateTimeWithYear、长格式formatDateTime等变体gallery 的date-time、date-time-seconds、date-time-short页面正是对它们的逐一展示。五、locale 数据模型决定输出的五个维度无论是 gallery 演示还是真实业务代码调用格式化函数都必须提供完整的FrontendLocaleData。该类型及全部枚举定义于 src/data/translation.tsexport interface FrontendLocaleData { language: string; number_format: NumberFormat; time_format: TimeFormat; date_format: DateFormat; first_weekday: FirstWeekday; time_zone: TimeZone; }其中对formatDateTimeNumeric直接生效的有三个字段枚举取值对数值日期时间格式的影响language语言代码字符串决定Intl使用的语言环境进而决定数字分隔符、AM/PM 写法等date_formatlanguage/system/DMY/MDY/YMD决定日期部分的排列顺序或是否跟随语言默认值time_formatlanguage/system/am_pm(12) /twenty_four(24)决定 12 小时制还是 24 小时制time_zonelocal/server决定格式化所依据的时区归属number_format与first_weekday虽然不参与该函数的输出但在真实前端中它们与语言偏好一起持久化通过saveTranslationPreferences/subscribeTranslationPreferences读写language用户数据因此在构造FrontendLocaleData时同样需要给出合法取值。六、时区解析resolveTimeZone 的兜底策略src/common/datetime/resolve-time-zone.ts 中resolveTimeZone的规则是export const resolveTimeZone (option: TimeZone, serverTimeZone: string) option TimeZone.local RESOLVED_TIME_ZONE ? LOCAL_TIME_ZONE : serverTimeZone;即当用户选择local时优先使用浏览器通过Intl.DateTimeFormat().resolvedOptions().timeZone解析出的 IANA 时区名若浏览器无法给出合法 IANA 名称例如部分 Android 模拟器只返回00:00这类偏移量则回退到服务端时区serverTimeZone。gallery 演示页使用demoConfigsrc/fake_data/demo_config.ts作为HassConfig其time_zone固定为America/Los_Angelesversion为DEMO。七、Gallery 演示页语言 × 时间格式矩阵页面主体是自定义元素demo-date-time-date-time-numericgallery/src/pages/date-time/date-time-numeric.ts它把上述机制渲染成一张可交互的对照表时间选择器顶部ha-control-select提供Now、12:15:30 AM、06:15:30 AM、12:15:30 PM、06:15:30 PM五个时间点定义于 gallery/src/data/date-options.ts。选择后会把对应时分秒写入Date对象方便观察不同时刻在 12/24 小时制下的呈现差异。语言矩阵遍历translationMetadata.translations来源为 src/resources/translations-metadata.ts内容是构建产物translationMetadata.json为每种语言显示nativeName并对同一时刻输出三列Default (lang)time_format: TimeFormat.language即跟随该语言默认习惯12 Hourstime_format: TimeFormat.am_pm24 Hourstime_format: TimeFormat.twenty_four。其余 locale 字段number_format、date_format、first_weekday、time_zone统一使用以en为基线的defaultLocale仅替换language与time_format从而保证三列的差异完全由语言与时间格式两个变量驱动。gallery 的这些页面运行在真实 Home Assistant 实例之外配合假状态即可安全复现界面参见 gallery/src/pages/concepts/home.markdown 的说明。八、性能细节memoizeOne 缓存formatDateTimeNumeric及其底层各格式化器都使用memoizeOne对Intl.DateTimeFormat实例做缓存。以formatTimeMem为例缓存的 key 是(locale, serverTimeZone)组合——只要语言、时间格式与时区未变化就复用同一个Intl.DateTimeFormat实例避免在每次渲染如卡片列表重绘时重复构造格式化器。这与useAmPm的 memoize 化一样都是为了控制高频 UI 渲染下的开销。九、业务调用示例在真实前端代码如卡片、仪表盘组件中调用formatDateTimeNumeric的典型方式如下import { formatDateTimeNumeric } from ../../common/datetime/format_date_time; import { TimeFormat } from ../../data/translation; import type { FrontendLocaleData, HomeAssistant } from ../../types; const formatted formatDateTimeNumeric( new Date(), { ...hass.locale, time_format: TimeFormat.am_pm, // 或 twenty_four覆盖用户默认 }, hass.config );关键点hass.locale通常已由前端全局加载并包含用户在个人资料中的语言偏好若需要强制某种时间制式例如日志时间戳固定 24 小时可像 gallery 演示页那样在展开...hass.locale后覆盖time_format第三个参数hass.config提供time_zone是时区解析的兜底来源。十、小结formatDateTimeNumeric是 Home Assistant frontend 中数值日期 时间组合格式的统一入口日期部分由formatDateNumeric依据DateFormat决定排列顺序时间部分由formatTime依据useAmPm探测结果决定 12/24 小时制两者共享同一套resolveTimeZone时区策略并全部基于原生Intl.DateTimeFormat实现。gallery 中的 Date-Time Format (Numeric) 页面则通过语言 × 时间格式矩阵直观呈现了各语言环境下的真实输出配合 test/common/datetime/format_date_time.test.ts 中的断言可作为多语言日期时间格式化的权威参考与回归测试基线。赞分享前端智能家居UI组件【免费下载链接】frontend:lollipop: Frontend for Home Assistant项目地址https://gitcode.com/gh_mirrors/frontend149/frontend点击查看免费下载相关推荐Home Assistant Frontend 日期时间格式化实战深入解析 formatDateTimeWithSeconds 的语言与时制机制Home Assistant Frontend 日期时间格式化实战深入解析 formatDateTimeWithSeconds 的语言与时制机制 Home A前端智能家居UI组件Home Assistant Frontend 日期时间短格式解析formatShortDateTime 的多语言格式化实现与 Gallery 实践Home Assistant Frontend 日期时间短格式解析formatShortDateTime 的多语言格式化实现与 Gallery 实践 导读 本前端智能家居UI组件Home Assistant 前端数值日期格式化完整指南读懂 formatDateNumeric 与多语言日期顺序Home Assistant 前端数值日期格式化完整指南读懂 formatDateNumeric 与多语言日期顺序 本指南围绕 Home Assistant前端智能家居UI组件上一篇群晖 DSM 7.2.2 恢复 Video Station一个脚本三步装好并开启 HEVC 解码下一篇3分钟装好 Axure中文语言包让 Axure RP 9/10/11 开口说中文创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
