Parcelable 实现生成器

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.kt

@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.kt

支持的类型

@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)
    }
}
Parcelize.kt

您可以使用 @TypeParceler 或 @WriteWith 注解来应用外部 Parceler：

// Class-local parceler
@Parcelize
@TypeParceler<ExternalClass, ExternalClassParceler>()
class MyClass(val external: ExternalClass) : Parcelable
Parcelize.kt

// Property-local parceler
@Parcelize
class MyClass(@TypeParceler<ExternalClass, ExternalClassParceler>() val external: ExternalClass) : Parcelable
Parcelize.kt

// Type-local parceler
@Parcelize
class MyClass(val external: @WriteWith<ExternalClassParceler>() ExternalClass) : Parcelable
Parcelize.kt

从 Parcel 创建数据

在 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)
}
Parcelize.kt

跳过序列化中的属性

如果您想跳过某些属性的序列化，请使用 @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
}
Parcelize.kt

使用 android.os.Parcel.writeValue 序列化属性

您可以使用 @RawValue 为类型添加注释，使 Parcelize 为相应属性使用 Parcel.writeValue。

@Parcelize
class MyClass(val external: @RawValue ExternalClass) : Parcelable
Parcelize.kt

如果属性的值不受 Android 原生支持，则可能会在运行时失败。

如果无法以其他方式序列化属性，Parcelize 也可能会要求您使用此注释。

使用密封类和密封接口进行 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
Parcelize.kt

为 Kotlin Multiplatform 设置 Parcelize

注意： Parcelize 库专为 Android 设计。虽然可以在多平台项目中添加此库，但请注意，功能会受到严重限制。

在 Kotlin 2.0 之前，您可以通过使用 expect 和 actual 为 Parcelize 注解设置别名来使用 Parcelize：

// 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
Parcelize.kt

// Platform code
// package example

// No typealias for MyParcelize here
actual typealias MyParcelable = android.os.Parcelable
actual typealias MyIgnoredOnParcel = kotlinx.parcelize.IgnoredOnParcel
Parcelize.kt

由于 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
ParcelizeDataClass.kt

主要构造函数及其所有属性必须可从 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
Parcelize.kt

主要构造函数中的非 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)
Parcelize.kt

// 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。