पार्स किया जा सकने वाला लागू करने वाला जनरेटर

kotlin-parcelize प्लगिन, Parcelable लागू करने वाला जनरेटर उपलब्ध कराता है.

Parcelable के लिए सहायता शामिल करने के लिए, अपने ऐप्लिकेशन की build.gradle फ़ाइल में Gradle प्लग इन जोड़ें:

ग्रूवी

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
  • काम करने वाले सभी टाइप के ऐरे
  • काम करने वाले सभी टाइप के वैल्यू के लिए, वैल्यू न डालने की अनुमति वाले वर्शन

कस्टम 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

पार्सल से डेटा बनाएं

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 का इस्तेमाल करना

किसी प्रॉपर्टी के लिए Parcelize का इस्तेमाल Parcel.writeValue करने के लिए, उस टाइप के लिए @RawValue का इस्तेमाल किया जा सकता है.

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

अगर प्रॉपर्टी की वैल्यू, Android में पहले से काम नहीं करती, तो हो सकता है कि रनटाइम के दौरान यह काम न करे.

अगर प्रॉपर्टी को क्रम में लगाने का कोई और तरीका नहीं है, तो भी पार्सलाइज़ करने के लिए आपको इस एनोटेशन का इस्तेमाल करने की ज़रूरत पड़ सकती है.

सील की गई क्लास और सील किए गए इंटरफ़ेस की मदद से पार्सल करना

पार्सलाइज़ करने के लिए क्लास को पार्स करना होता है, ताकि ऐब्स्ट्रैक्ट नहीं बनाया जा सके. यह शर्त, सील की गई क्लास पर लागू नहीं होती. जब सील की गई क्लास पर @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 से पहले, आप 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 और इसके बाद के वर्शन में, प्लगिन को ट्रिगर करने वाले एलियासिंग एनोटेशन काम नहीं करते. इस समस्या से बचने के लिए, प्लगिन में additionalAnnotation पैरामीटर के तौर पर नया Parcelize एनोटेशन दें.

// 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 का इस्तेमाल किया जा सकता है. अगर कस्टम पार्सल करने वाले टूल चुने जाते हैं, तो उन्हें 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

मुख्य कंस्ट्रक्टर में val या var पैरामीटर नहीं

Kotlin 2.1.0 के बाद से उपलब्ध.

इस सुविधा को चालू करने के लिए, parcelize प्लग इन के आर्ग्युमेंट में experimentalCodeGeneration=true जोड़ें.

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)

// 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 प्लग इन से जुड़ी कोई समस्या आती है, तो गड़बड़ी की शिकायत की जा सकती है.