このページは Cloud Translation API によって翻訳されました。

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 でサポートされている必要があります。カスタム 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

プライマリコンストラクタ内の var パラメータまたは 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 プラグインで問題が発生した場合は、バグを報告してください。