编程 ICU4X 2.0 的 DateTime:yMMMd 要写 YMD::medium(),month+minute 组合不存在

2026-11-20 00:06:26

ICU4X 2.0 的 DateTime API:skeleton 字符串退场,1.x 的调用点要整体重写

结论

ICU4X 2.0 按 UTS 35 中新的 semantic datetime skeletons 规范重新设计了 DateTime 组件。DateTime 格式化的入口从 skeleton 字符串(yMMMd、jmsV 这一类)改成“先选一个固定的 field set,再用 options 微调”。field set 的数量是固定的,覆盖所有合法的字段组合。

代价是接口层面的断裂:从 2.0-beta1 起,DateTimeFormatter 与 icu_datetime 大部分被重写,改为按 LDML 46 只格式化字段子集;ICU4X 1.x 的 DateTimeFormatter 所有调用点都需要更新,官方建议直接按新 crate 文档从头写,不建议逐行改。

三种写法对照

ICU 经典 skeletonECMA-402 components bagICU4X 2.0 fieldset
yMMMd{ year: "numeric", month: "abbreviated", day: "numeric" }fieldsets::YMD::medium()
MdEjm{ month: "numeric", day: "numeric", weekday: "short", hour: "numeric", minute: "numeric" }fieldsets::MDE::short().time_hm()
jmsV{ hour: "numeric", minute: "numeric", second: "numeric", timeZoneName: "generic" }fieldsets::T::hms().zone(zone::GenericShort)

左列是几十年来 ICU 用户实际写的东西,中列是 ECMA-402 的写法,右列则是 ICU4X 2.0 在 Rust 里的形状:fieldset 用类型固定字段集合,长度、时区名风格这类差异走 options。

固定 fieldset 带来的直接后果

避免拼错 skeleton。 ICU skeleton 最常见的错误是把正确的 yMd 写成 YMd 或 ymd。大小写差异在字符串里没有任何约束,拼错往往不会报错,只是输出不对。fieldset 是类型,拼错在编译期就不会通过。

只能表达合法组合。 API 层面直接不允许无意义的字段和选项搭配。典型例子是“month with minute”在 ICU4X 里不存在对应 fieldset,不会出现 “December 5 的 7:10 被渲染成 December 10” 这类结果。

可以用 option 做 skeleton 做不到的事。 例如年的风格(year style),可以自动插入 BCE 这类纪元;旧的 skeleton 或 components bag 表达不了这个。

时间精度也能作为 option。 分钟为零时可以隐藏分钟,这在 skeleton 字符串里同样无法描述。

按字段裁剪数据。 fieldset 决定要加载哪些数据,只用年/月/日或只用时间字段的应用不会带上星期名数据,开销降到实际需要的部分。

这几条合起来是同一个设计取向:把“用户想要什么格式”从一段任意字符串,收窄成有限集合加少量开关。

迁移中的改名与语义变化

icu_datetime

这个 crate 变动量大,建议从头重新认识,不要按 1.x 的记忆去改。

  • .hm() 从方法改为构造器。
  • date fieldsets 上新增 .time_hm 与 .time_hms,日期字段集要带时间就挂这两个。
  • .with_length 改名 .for_length。
  • Length 不再有显式 repr(u8) 判别值,别再把它的数值当作稳定表示来做序列化或比较。
  • 修复 datetime 格式化里使用了不正确的 datetime skeleton 的问题。
  • 拆分 DateTimeWriteError 并重写文档。
  • 移除 SubsecondError,改为 Option API。
  • ZonedDateTime::try_from_str 改名 try_full_from_str。
  • 移除死类型 DateTimeSkeletons 及其 data marker。
  • ConflictingField 错误改为携带先前加载的字段,报冲突时能看到已经成功加载的内容,定位比原来直接。

icu_time

同样建议从头读。除了 ZonedDateTime::try_from_str 也改名 try_full_from_str(两个 crate 都要跟着改)之外,还有几处新增:

  • 新增 ZoneNameTimestamp 类型,专门用于时区显示名。
  • 新增 from_epoch_milliseconds_and_utc_offset 及相关 API,可以直接从毫秒时间戳加 UTC offset 构造。
  • 新增 Time::noon()。
  • DateTime、ZonedDateTime 实现 Clone 与 Copy,值语义的传递不必再借用或克隆整块。

组件边界

icu_calendar 只做历法计算,icu_time 承接了原先 icu_calendar 与 icu_timezone 的部分职责;icu_timezone 永久停在 1.5,不再跟随主线演进。

迁移顺序

  1. 先确认时区侧的输入来源:try_from_str 的调用点全部换成 try_full_from_str,icu_datetime 和 icu_time 两处都查一遍。
  2. 处理 icu_time 的新值类型:需要时区显示名的地方改用 ZoneNameTimestamp;从毫秒时间戳加 offset 构造的路径换成 from_epoch_milliseconds_and_utc_offset;接收 DateTime / ZonedDateTime 的函数可以按 Copy 调整签名。
  3. 重写 fieldset:按 §对照表 把每个旧 skeleton 落到一个固定 fieldset,长度用 for_length(原 with_length),时间部分挂 time_hm / time_hms,.hm() 改成构造器用法。
  4. 清理错误与精度处理:SubsecondError 的分支改为读 Option;ConflictingField 的处理逻辑适配新增的已加载字段信息;DateTimeWriteError 按拆分后的类型重新匹配。
  5. 删掉对 DateTimeSkeletons 及 Length 判别值的任何依赖。

与站内 #8673 的分工

#8673 讲的是 ICU4X 1.5→2.0 的数据链与 crate 冻结(postcard 不兼容、blob schema v3、icu_datagen 拆分、fallback 责任、Preferences 按值传入);本篇只覆盖 DateTime / icu_time 的 API 形态变化,两者不重叠。

项目信息

  • GitHub:
  • 文档站点:icu4x.unicode.org,2.0 / 2.1 / 2.2 / 2.3 / 2.4 有分版本教程
  • crates.io 与 docs.rs 均有发布
  • 2.0 release tag:icu@2.0.0
复制全文 生成海报 ICU4X ICU Rust i18n 国际化 CLDR DateTime

推荐文章

程序员茄子在线接单