Генератор программных реализаций

Плагин 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
• Массивы всех поддерживаемых типов
• Нулевые версии всех поддерживаемых типов

Таможенные 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

Создать данные из посылки

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

Вы можете аннотировать тип с помощью @RawValue , чтобы Parcelize использовал Parcel.writeValue для этого свойства.

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

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

Использование аннотации `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
Parcelize.kt

Настройка Parcelize для Kotlin на нескольких платформах

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