Генератор реализации Parcelable

Плагин kotlin-parcelize содержит генератор кода для реализации Parcelable.

Чтобы добавить поддержку Parcelable, добавьте плагин Gradle в файл build.gradle вашего приложения:

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.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 поддерживает следующие типы:

• Примитивные типы (и их упакованные версии)
• Объекты и перечисления
• 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.
• Массивы всех поддерживаемых типов
• Nullable-версии всех поддерживаемых типов

Свои цвета 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:

// 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 для сериализации свойства

Чтобы Parcelize использовал для свойства Parcel.writeValue, добавьте к типу аннотацию @RawValue.

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

Если значение свойства не поддерживается Android, во время выполнения может произойти сбой.

Кроме того, Parcelize может потребовать использовать эту аннотацию, если нет другого способа сериализовать свойство.

Как использовать Parcelable с запечатанными классами и интерфейсами

Для 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

Как настроить Parcelize для Kotlin Multiplatform

До версии Kotlin 2.0 вы могли использовать Parcelize, создавая псевдонимы для аннотаций Parcelize с помощью expect и actual:

// 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. Пользовательские парселеры, если они выбраны, должны быть указаны в классе 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, вы можете сообщить об ошибке.