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 经典 skeleton | ECMA-402 components bag | ICU4X 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,改为OptionAPI。 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,不再跟随主线演进。
迁移顺序
- 先确认时区侧的输入来源:
try_from_str的调用点全部换成try_full_from_str,icu_datetime和icu_time两处都查一遍。 - 处理
icu_time的新值类型:需要时区显示名的地方改用ZoneNameTimestamp;从毫秒时间戳加 offset 构造的路径换成from_epoch_milliseconds_and_utc_offset;接收DateTime/ZonedDateTime的函数可以按Copy调整签名。 - 重写 fieldset:按 §对照表 把每个旧 skeleton 落到一个固定 fieldset,长度用
for_length(原with_length),时间部分挂time_hm/time_hms,.hm()改成构造器用法。 - 清理错误与精度处理:
SubsecondError的分支改为读Option;ConflictingField的处理逻辑适配新增的已加载字段信息;DateTimeWriteError按拆分后的类型重新匹配。 - 删掉对
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