Kotlin logo

The Kotlin Blog

Kotlin Programming Language by JetBrains

Libraries

kotlinx-datetime 0.2.0 现已发布

今天我们来探索一个与Kotlin 1.5.0一起发布的,用于日期和时间处理的多平台库的新版本——kotlinx-datetime0.2.0。 去年夏天,我们发布了库的首个版本,而现在是我们迈向稳定版的下一步。

我们在Kotlin 1.4线上活动中介绍了 kotlinx-datetime:您可以观看 Ilya Gorbunov的演讲,以详细了解库的设计原理和功能。 如果您对 kotlinx-datetime 有任何疑问,我们建议您参加即将到来的 Kotlin 1.5在线活动,并将其提交给 Kotlin团队。

在线活动注册

0.2.0版本带来了很多改进:

  • 支持 kotlinx.serialization 
  • DateTimePeriod 组成属性标准化
  • 允许从携带时区偏移量的字符串中解析 Instant

尝试一下! 只需保安装了 Kotlin 1.5.0 就行。 我们来详细了解一下功能。

请注意kotlinx-datetime 0.2.0仍然是实验性的。 其API可能会随时变更。

支持 kotlinx.serialization

kotlinx-datetime 提供了自己的类型来表示日期和时间:例如 Instant LocalDateTimeZone。 在版本0.2.0,受 kotlinx.serialization 库的支持,这些类型都可以序列化。 您可以在 kotlinx.datetime.serializers 包中找到我们提供的一组序列化器。

大部分的类型都拥有默认序列化器。 这些类型是 InstantLocalDateLocalDateTimeDateTimePeriodDatePeriodTimeZone,以及 ZoneOffset。 它们能作为可序列化类的属性,而不需要显式注解。

默认序列化器基于以 ISO 8601 字符串表示形式的类型,并通过 toString()/parse()来序列化和反序列化。

其中部分类型拥有可替换的序列化器,允许使用不同的序列化策略,这比指定格式的默认策略更高效。 例如,LocalDate 可被 LocalDateComponentSerializer 逐个组件形式地序列化。 使用常规的 @Serializable(with = ...)注解明确地选择序列化器。 您也可以通过 contextual serializer 延迟这选项的执行时间。

还有一些没有序列化器的类型:DayOfWeekMonthkotlinx.serialization 作为普通枚举所支持。

请谨记 kotlinx.serialization 只是 kotlinx-datetime 的可选依赖。 要使用序列化功能,请在项目依赖的 kotlinx-datetime 后加上 kotlinx-serialization-core

DateTimePeriod组成属性标准化

DateTimePeriod 类表示 2 个 instants 之间的时间段,时间段可以是各种时间单位类型的组合:年,月,日,小时,分钟,秒和纳秒。 对于每种时间单位类型,该类都有一个对应的属性,这个属性在构造函数的参数里接收值,例如:DateTimePeriod(months = 14,minutes = 90)

在之前该组成属性是独立的,只保存传递给构造函数的值。 但这会导致两个组成属性不同的对象虽然不相等,但其ISO表示形式相同的情况。 对这样的值序列化,然后反序列化可能会和原始值不同。

在这个版本,我们修改了 DateTimePeriod 的内部表示,在构造函数中增加了让组成属性标准化的步骤。 现在,内部将组成属性标准化为纳秒,日和月的组合,这解决了最初的问题,并且即使组成属性的 getter 返回的值非常大,也很易读。

从带时区偏移量的字符串中解析 Instant

Instant 类表示一个时刻。 该库可以解析符合 ISO 8601 标准的日期和时间字符串。

在 0.2.0 之前,我们仅接受以Z时区指示符结尾的格式,例如 2021-01-02T03:02:01Z,这意味着时区偏移量必须为UTC+0。 从现在开始,我们还支持非零的时区偏移量:

尝试一下

kotlinx-datetime 0.2.0 已经发布到 Maven Central。 在您的项目中尝试一下吧:

  • 确保您的 repository 已设置 Maven Central。
  • 添加 kotlinx-datetime 依赖项 (如果您正在开发多平台项目,请不要忘记指定源集)。

要获取该库的更多详细说明,请查看我们的 README

分享您的反馈

这个库是实验性的,其 API 仍可能发生变更。 我们正在逐步迈向稳定版,而您的反馈会被采纳。

试用 kotlinx-datetime 0.2.0 并与我们分享您的经验! 向项目的问题跟踪器报告您遇到的任何问题,也可以在我们的Slack 中提出任何问题(可以在这里获得邀请)。

特别感谢由来自 Kotlin 社区的 黄智聪 (pye52) 为本篇博文提供中文译文。

Discover more