kotlinx-datetime 0.2.0 现已发布

Lei

Read this post in other languages:

• English
,
• Deutsch
,
• 日本語
,
• 한국어
,
• Русский

今天我们来探索一个与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.serialization

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

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

import kotlinx.datetime.LocalDate
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json
import kotlinx.serialization.encodeToString

@Serializable
class Person(val name: String, val birthDate: LocalDate)

fun main() {
    val harry = Person("Harry", LocalDate(1980, 7, 31))
    println(Json.encodeToString(harry))
    // {"name":"Harry","birthDate":"1980-07-31"}
}

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

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

import kotlinx.datetime.LocalDate
import kotlinx.datetime.serializers.LocalDateComponentSerializer
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json
import kotlinx.serialization.encodeToString

@Serializable
class Person(
    val name: String,
    @Serializable(with = LocalDateComponentSerializer::class)
    val birthDate: LocalDate
)

fun main() {
    val harry = Person("Harry", LocalDate(1980, 7, 31))
    println(Json.encodeToString(harry))
    // {"name":"Harry","birthday":{"year":1980,"month":7,"day":31}}
}

还有一些没有序列化器的类型：DayOfWeek 和 Month 被 kotlinx.serialization 作为普通枚举所支持。

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

DateTimePeriod组成属性标准化

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

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

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

val period1 = DateTimePeriod(months = 14, minutes = 90)
val period2 = DateTimePeriod(years = 1, months = 2, hours = 1, minutes = 30)
println(period1 == period2)  // true
println(period1)             // P1Y2MT1H30M // ISO-8601
println(period2)             // P1Y2MT1H30M // ISO-8601
println(period1.years)       // 1
println(period1.months)      // 2
println(period1.days)        // 0
println(period1.hours)       // 1
println(period1.minutes)     // 30
println(period1.seconds)     // 0
println(period1.nanoseconds) // 0

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

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

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

val instant1 = Instant.parse("2021-01-02T03:02:01Z")
val instant2 = Instant.parse("2021-01-02T06:02:01+03:00")
println(instant1) // 2021-01-02T03:02:01Z
println(instant2) // 2021-01-02T03:02:01Z

尝试一下

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

• 确保您的 repository 已设置 Maven Central。

repositories {
    mavenCentral()
}

• 添加 kotlinx-datetime 依赖项 (如果您正在开发多平台项目，请不要忘记指定源集)。

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.2.0")
}

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

分享您的反馈

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

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

Subscribe to Kotlin Blog updates

Subscribe form

By submitting this form, I agree to the JetBrains Privacy Policy Notification icon

提交此表单，即表示我同意 JetBrains s.r.o. ("JetBrains") 使用我的姓名、电子邮件地址和位置数据向我发送简报和商业通讯，并为此目的而处理我的个人数据。我同意 JetBrains 根据 JetBrains 隐私政策为此目的使用第三方服务处理上述数据。我了解我可以在我的个人资料中随时撤回此同意。此外，每封电子邮件中也都包含退订链接。

Submit

谢谢！