kotlin-parcelize
插件提供了一个 Parcelable
实现生成器。
如需添加对 Parcelable
的支持,请将 Gradle 插件添加到应用的 build.gradle
文件中:
Groovy
plugins { id 'kotlin-parcelize' }
Kotlin
plugins { id("kotlin-parcelize") }
当您使用 @Parcelize
为类添加注解时,系统会自动生成一个 Parcelable
实现,如以下示例所示:
import kotlinx.parcelize.Parcelize
@Parcelize
class User(val firstName: String, val lastName: String, val age: Int): Parcelable
@Parcelize
要求在主要构造函数中声明所有序列化属性。该插件会针对每个属性发出警告,并在类正文中声明一个后备字段。此外,如果主要构造函数的某些参数不是属性,则不能应用 @Parcelize
。
如果您的类需要更高级的序列化逻辑,请将其写在某个伴随类中:
@Parcelize
data class User(val firstName: String, val lastName: String, val age: Int) : Parcelable {
private companion object : Parceler<User> {
override fun User.write(parcel: Parcel, flags: Int) {
// Custom write implementation
}
override fun create(parcel: Parcel): User {
// Custom read implementation
}
}
}
支持的类型
@Parcelize
支持多种类型:
- 基元类型(及其 boxed 版本)
- 对象和枚举
String
、CharSequence
Duration
Exception
Size
、SizeF
、Bundle
、IBinder
、IInterface
、FileDescriptor
SparseArray
、SparseIntArray
、SparseLongArray
、SparseBooleanArray
- 所有
Serializable
(包括Date
)和Parcelable
实现 - 所有受支持类型的集合:
List
(映射到ArrayList
)、Set
(映射到LinkedHashSet
)、Map
(映射到LinkedHashMap
)- 此外,还有一些具体实现:
ArrayList
、LinkedList
、SortedSet
、NavigableSet
、HashSet
、LinkedHashSet
、TreeSet
、SortedMap
、NavigableMap
、HashMap
、LinkedHashMap
、TreeMap
、ConcurrentHashMap
- 此外,还有一些具体实现:
- 所有受支持类型的数组
- 所有受支持类型的可为 null 版本
自定义 Parceler
如果系统不能直接支持您的类型,您可以为其写一个 Parceler
映射对象。
class ExternalClass(val value: Int)
object ExternalClassParceler : Parceler<ExternalClass> {
override fun create(parcel: Parcel) = ExternalClass(parcel.readInt())
override fun ExternalClass.write(parcel: Parcel, flags: Int) {
parcel.writeInt(value)
}
}
您可以使用 @TypeParceler
或 @WriteWith
注解来应用外部 Parceler:
// Class-local parceler
@Parcelize
@TypeParceler<ExternalClass, ExternalClassParceler>()
class MyClass(val external: ExternalClass) : Parcelable
// Property-local parceler
@Parcelize
class MyClass(@TypeParceler<ExternalClass, ExternalClassParceler>() val external: ExternalClass) : Parcelable
// Type-local parceler
@Parcelize
class MyClass(val external: @WriteWith<ExternalClassParceler>() ExternalClass) : Parcelable
从地块创建数据
在 Java 代码中,您可以直接访问 CREATOR
字段。
class UserCreator {
static User fromParcel(Parcel parcel) {
return User.CREATOR.createFromParcel(parcel);
}
}
在 Kotlin 中,您不能直接使用 CREATOR
字段。请改用 kotlinx.parcelize.parcelableCreator
。
import kotlinx.parcelize.parcelableCreator
fun userFromParcel(parcel: Parcel): User {
return parcelableCreator<User>().createFromParcel(parcel)
}
从序列化中跳过属性
如果您想跳过某些要分块的项,请使用 @IgnoredOnParcel
注解。它还可用于类正文中的属性,以关闭有关该属性未序列化的警告。带有 @IgnoredOnParcel
注解的构造函数属性必须具有默认值。
@Parcelize
class MyClass(
val include: String,
// Don't serialize this property
@IgnoredOnParcel val ignore: String = "default"
): Parcelable {
// Silence a warning
@IgnoredOnParcel
val computed: String = include + ignore
}
使用 android.os.Parcel.writeValue 序列化属性
您可以使用 @RawValue
为类型添加注解,以便 Parcelize 对该属性使用 Parcel.writeValue
。
@Parcelize
class MyClass(val external: @RawValue ExternalClass): Parcelable
如果属性的值不受 Android 原生支持,则此操作可能会在运行时失败。
如果没有其他可以序列化属性的方法,使用 Parcelize 可能还需要使用此注释。
使用密封类和密封接口进行分块
Parcelize 需要一个 Parcelize 类,使其不是抽象类。此限制不适用于密封类。将 @Parcelize
注解用于密封类时,无需对派生类重复该注解。
@Parcelize
sealed class SealedClass: Parcelable {
class A(val a: String): SealedClass()
class B(val b: Int): SealedClass()
}
@Parcelize
class MyClass(val a: SealedClass.A, val b: SealedClass.B, val c: SealedClass): Parcelable
为 Kotlin 多平台设置 Parcelize
在 Kotlin 2.0 之前,您可以使用 Parcelize,方法是将 Parcelize 注解与 expect
和 actual
进行重命名:
// Common code
package example
@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.BINARY)
expect annotation class MyParcelize()
expect interface MyParcelable
@Target(AnnotationTarget.PROPERTY)
@Retention(AnnotationRetention.SOURCE)
expect annotation class MyIgnoredOnParcel()
@MyParcelize
class MyClass(
val x: String,
@MyIgnoredOnParcel val y: String = ""
): MyParcelable
// Platform code
package example
actual typealias MyParcelize = kotlinx.parcelize.Parcelize
actual typealias MyParcelable = android.os.Parcelable
actual typealias MyIgnoredOnParcel = kotlinx.parcelize.IgnoredOnParcel
在 Kotlin 2.0 及更高版本中,不支持用于触发插件的注解别名。为解决此问题,请改为将新的 Parcelize
注解作为 additionalAnnotation
参数提供给插件。
// Gradle build configuration
kotlin {
androidTarget {
compilerOptions {
// ...
freeCompilerArgs.addAll("-P", "plugin:org.jetbrains.kotlin.parcelize:additionalAnnotation=example.MyParcelize")
}
}
}
// Common code
package example
@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.BINARY)
// No `expect` keyword here
annotation class MyParcelize()
expect interface MyParcelable
@Target(AnnotationTarget.PROPERTY)
@Retention(AnnotationRetention.SOURCE)
expect annotation class MyIgnoredOnParcel()
@MyParcelize
class MyClass(
val x: String,
@MyIgnoredOnParcel val y: String = ""
): MyParcelable
// Platform code
package example
// No typealias for MyParcelize here
actual typealias MyParcelable = android.os.Parcelable
actual typealias MyIgnoredOnParcel = kotlinx.parcelize.IgnoredOnParcel
由于 Parcel
接口仅适用于 Android,因此 Parcelize 不会在其他平台上生成任何代码,因此这些平台上的任何 actual
实现都可以为空。此外,在常规代码中,也无法使用任何需要引用 Parcel
类的注解,例如 @WriteWith
。
实验功能
数据类序列化器
从 Kotlin 2.1.0 开始提供。
借助 DataClass
注解,可以对数据进行序列化,就像将数据类本身带有 Parcelize
注解一样。此注解需要选择启用 kotlinx.parcelize.Experimental
。
@file:OptIn(kotlinx.parcelize.Experimental::class)
data class C(val a: Int, val b: String)
@Parcelize
class P(val c: @DataClass C) : Parcelable
主要构造函数及其所有属性必须可从 Parcelable
类访问。此外,Parcelize
必须支持数据类的所有主要构造函数属性。自定义 Parceler(如果选择)应在 Parcelable
类(而非数据类)中指定。如果数据类同时实现了 Serializable
,则 @DataClass
注解优先:系统不会使用 android.os.Parcel.writeSerializable
。
一个实际的用例是序列化 kotlin.Pair
。另一个实用示例是简化多平台代码:常规代码可以将数据层声明为数据类,然后 Android 代码可以使用序列化逻辑对其进行增强,从而无需在常规代码中使用 Android 专用注解和类型别名。
// Common code:
data class MyData(val x: String, val y: MoreData)
data class MoreData(val a: String, val b: Int)
// Platform code:
@OptIn(kotlinx.parcelize.Experimental::class)
@Parcelize
class DataWrapper(val wrapped: @DataClass MyData): Parcelable
主要构造函数中的非 val 或 var 参数
从 Kotlin 2.1.0 开始提供。
如需启用此功能,请将 experimentalCodeGeneration=true
添加到 parcelize 插件参数。
kotlin {
compilerOptions {
// ...
freeCompilerArgs.addAll("-P", "plugin:org.jetbrains.kotlin.parcelize:experimentalCodeGeneration=true")
}
}
此功能解除了对主构造函数参数必须为 val
或 var
的限制。这解决了将 parcelize 与继承搭配使用时的一个痛点,之前需要使用 open
属性。
// base parcelize
@Parcelize
open class Base(open val s: String): Parcelable
@Parcelize
class Derived(
val x: Int,
// all arguments have to be `val` or `var` so we need to override
// to not introduce new property name
override val s: String
): Base(s)
// experimental code generation enabled
@Parcelize
open class Base(val s: String): Parcelable
@Parcelize
class Derived(val x: Int, s: String): Base(s)
此类参数只能用于基类构造函数的参数中。不允许在类的正文中引用它们。
@Parcelize
class Derived(s: String): Base(s) { // allowed
@IgnoredOnParcel
val x: String = s // ERROR: not allowed.
init {
println(s) // ERROR: not allowed
}
}
反馈
如果您在使用 kotlin-parcelize
Gradle 插件时遇到任何问题,可以提交 bug。