Parcelable 実装生成ツール

kotlin-parcelize プラグインには、Parcelable 実装生成ツールが用意されています。

Parcelable のサポートを組み込むには、アプリの build.gradle ファイルに次の 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 は、さまざまな型をサポートします。

  • プリミティブ型（およびそのボックス化バージョン）
  • オブジェクトと列挙型
  • 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 アノテーションを使用して、外部のパーセラーを適用できます。

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

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)
}

シリアル化からプロパティをスキップする

一部のプロパティをパーセル化から除外する場合は、@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 アノテーションを 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 でサポートされている必要があります。カスタム パーセラーは、選択した場合、データクラスではなく Parcelable クラスで指定する必要があります。データクラスが Serializable を同時に実装する場合、@DataClass アノテーションが優先され、android.os.Parcel.writeSerializable は使用されません。

この実用的なユースケースは、kotlin.Pair のシリアル化です。もう 1 つの有用な例は、マルチプラットフォーム コードの簡素化です。共通コードでデータレイヤをデータクラスとして宣言し、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 以降で利用できます。

この機能を有効にするには、parcelize プラグインの引数に experimentalCodeGeneration=true を追加します。

kotlin {
    compilerOptions {
        // ...
        freeCompilerArgs.addAll("-P", "plugin:org.jetbrains.kotlin.parcelize:experimentalCodeGeneration=true")
    }
}

この機能により、プライマリ コンストラクタの引数が val または var でなければならないという制限が解除されます。これにより、以前は open プロパティを使用する必要があった、継承で parcelize を使用する際の 1 つの課題が解決されます。

// 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 プラグインで問題が発生した場合は、バグを報告してください。