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 アノテーションをシールクラスで使用する場合、派生クラスに対して繰り返す必要はありません。

@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 でサポートされている必要があります。カスタム Parceler を選択した場合は、データクラスではなく 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 プラグインで問題が発生した場合は、バグを報告してください。