Parcelable 實作產生器

kotlin-parcelize 外掛程式提供 Parcelable 實作產生器。

如要納入 Parcelable 支援功能，請將 Gradle 外掛程式加入應用程式的 build.gradle 檔案：

GroovyKotlin
plugins {
    id 'kotlin-parcelize'
}
 
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 支援眾多類型：

  • 原始類型 (及其方塊化版本)
  • 物件和列舉
  • 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
  • 所有支援類型的陣列
  • 所有支援類型的可為空值版本

自訂 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
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 Multiplatform 設定 Parcelize

在 Kotlin 2.0 之前，您可以使用 Parcelize，方法是使用 expect 和 actual 為 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

// 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 支援。如果選擇「Custom Parcelers」，應在 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 的限制。這解決了使用 包裹與繼承取得的一個問題，先前必須使用 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 外掛程式時遇到任何問題，可以回報錯誤。