Gerador de implementação de Parcelable

O plug-in kotlin-parcelize (link em inglês) fornece um gerador de implementação de Parcelable.

Para incluir suporte à interface Parcelable, adicione o plug-in do Gradle ao arquivo build.gradle do app:

Groovy

plugins {
    id 'kotlin-parcelize'
}

Kotlin

plugins {
    id("kotlin-parcelize")
}

Quando você insere uma anotação com @Parcelize, uma implementação de Parcelable é gerada automaticamente, como mostrado no exemplo a seguir.

import kotlinx.parcelize.Parcelize

@Parcelize
class User(val firstName: String, val lastName: String, val age: Int): Parcelable

@Parcelize requer que todas as propriedades serializadas sejam declaradas no construtor principal. O plug-in emite um aviso em cada propriedade com um campo de backup declarado no corpo da classe. Além disso, não será possível aplicar @Parcelize se alguns dos parâmetros do construtor principal não forem propriedades.

Caso sua classe exija uma lógica de serialização mais avançada, escreva-a dentro de uma classe de acompanhamento:

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

Tipos com suporte

@Parcelize aceita uma grande variedade de tipos:

  • Tipos primitivos (e suas versões em caixa)
  • Objetos e enumerações
  • String, CharSequence
  • Duration
  • Exception
  • Size, SizeF, Bundle, IBinder, IInterface, FileDescriptor
  • SparseArray, SparseIntArray, SparseLongArray, SparseBooleanArray
  • Todas as implementações de Serializable (incluindo Date) e Parcelable
  • Coleções de todos os tipos com suporte: List (mapeado para ArrayList), Set (mapeado para LinkedHashSet), Map (mapeado para LinkedHashMap)
    • Além disso, algumas implementações concretas: ArrayList, LinkedList, SortedSet, NavigableSet, HashSet, LinkedHashSet, TreeSet, SortedMap, NavigableMap, HashMap, LinkedHashMap, TreeMap, ConcurrentHashMap
  • Matrizes de todos os tipos com suporte
  • Versões anuláveis de todos os tipos com suporte

Parcelers personalizados

Se o tipo não tiver suporte direto, crie um objeto de mapeamento Parceler para ele.

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

É possível aplicar parcelers externos usando anotações @TypeParceler ou @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

Criar dados de encomenda

No código Java, é possível acessar o campo CREATOR diretamente.

class UserCreator {
    static User fromParcel(Parcel parcel) {
        return User.CREATOR.createFromParcel(parcel);
    }
}

No Kotlin, não é possível usar o campo CREATOR diretamente. Em vez disso, use kotlinx.parcelize.parcelableCreator.

import kotlinx.parcelize.parcelableCreator

fun userFromParcel(parcel: Parcel): User {
    return parcelableCreator<User>().createFromParcel(parcel)
}

Ignorar propriedades da serialização

Se você quiser pular a divisão de algumas propriedades, use a notação @IgnoredOnParcel. Ele também pode ser usado em propriedades no corpo de uma classe para silenciar avisos sobre a propriedade não ser serializada. As propriedades do construtor anotadas com @IgnoredOnParcel precisam ter um valor padrão.

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

Usar android.os.Parcel.writeValue para serializar uma propriedade

É possível anotar um tipo com @RawValue para fazer com que o Parcelize use Parcel.writeValue para essa propriedade.

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

Isso pode falhar no momento da execução se o valor da propriedade não tiver suporte nativo do Android.

O Parcelize também pode exigir que você use essa anotação quando não houver outra maneira de serializar a propriedade.

Parcelar com classes e interfaces seladas

O método Parcelize exige que uma classe a ser dividida não seja abstrata. Essa limitação não se aplica a classes seladas. Quando a anotação @Parcelize é usada em uma classe selada, ela não precisa ser repetida para as classes derivadas.

@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

Configurar o Parcelize para o Kotlin Multiplatform

Antes do Kotlin 2.0, era possível usar o Parcelize criando um alias para as anotações com expect e 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

No Kotlin 2.0 e versões mais recentes, não há suporte para anotações de alias que acionam plug-ins. Para contornar isso, forneça uma nova anotação Parcelize como o parâmetro additionalAnnotation para o plug-in.

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

Como a interface Parcel só está disponível no Android, o Parcelize não gera nenhum código em outras plataformas. Portanto, qualquer implementação de actual pode ficar vazia. Também não é possível usar nenhuma anotação que exija a referência à classe Parcel, por exemplo, @WriteWith, em código comum.

Recursos experimentais

Serializador de classes de dados

Disponível desde o Kotlin 2.1.0.

A anotação DataClass permite serializar classes de dados como se elas fossem anotadas com Parcelize. Essa anotação requer a ativação de 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

O construtor principal e todas as propriedades dele precisam ser acessíveis na classe Parcelable. Além disso, todas as propriedades do construtor principal da classe de dados precisam ter suporte a Parcelize. Os parceladores personalizados, se escolhidos, precisam ser especificados na classe Parcelable, não na classe de dados. Se a classe de dados implementar Serializable ao mesmo tempo, a anotação @DataClass terá prioridade: android.os.Parcel.writeSerializable não será usado.

Um caso de uso prático para isso é a serialização de kotlin.Pair. Outro exemplo útil é simplificar código multiplataforma: o código comum pode declarar a camada de dados como classes de dados, que o código do Android pode aumentar com a lógica de serialização, removendo a necessidade de anotações específicas do Android e tipos de aliases no código comum.

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

Parâmetros não val ou var no construtor principal

Disponível desde o Kotlin 2.1.0.

Para ativar esse recurso, adicione experimentalCodeGeneration=true aos argumentos do plug-in de parcelização.

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

Esse recurso remove a restrição aos argumentos do construtor principal que precisam ser val ou var. Isso resolve um problema de usar o recurso de divisão com herança, que antes exigia o uso de propriedades 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)

// experimental code generation enabled
@Parcelize
open class Base(val s: String): Parcelable

@Parcelize
class Derived(val x: Int, s: String): Base(s)

Esses parâmetros só podem ser usados em argumentos para o construtor da classe base. Não é permitido fazer referência a eles no corpo da classe.

@Parcelize
class Derived(s: String): Base(s) { // allowed
    @IgnoredOnParcel
    val x: String = s // ERROR: not allowed.
    init {
        println(s) // ERROR: not allowed
    }
}

Feedback

Se você encontrar problemas com o plug-in do Gradle kotlin-parcelize, registre um bug.