เครื่องมือสร้างการใช้งานแบบพาร์เซล

ปลั๊กอิน kotlin-parcelize มีเครื่องมือสร้างการติดตั้งใช้งาน Parcelable

หากต้องการให้รองรับ Parcelable ให้เพิ่มปลั๊กอิน Gradle ลงในไฟล์ build.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

สร้างข้อมูลจากพัสดุ

ในโค้ด 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
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 แบบหลายแพลตฟอร์ม

ก่อนที่จะใช้ 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 ขึ้นไป ระบบจะไม่รองรับการกำกับเนื้อหาที่ใช้แทนที่ซึ่งทริกเกอร์ปลั๊กอิน หากต้องการหลีกเลี่ยงปัญหานี้ ให้ระบุคำอธิบายประกอบ 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 ต้องรองรับพร็อพเพอร์ตี้คอนสตรัคเตอร์หลักทั้งหมดของคลาสข้อมูล ตัวแบ่งกลุ่มที่กำหนดเอง (หากเลือก) ควรระบุไว้ในคลาส 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

หากต้องการเปิดใช้ฟีเจอร์นี้ ให้เพิ่ม experimentalCodeGeneration=true ลงในอาร์กิวเมนต์ปลั๊กอินพาร์ซ

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

ฟีเจอร์นี้ยกเลิกข้อจำกัดที่ว่าอาร์กิวเมนต์คอนสตรัคเตอร์หลักต้องเป็น val หรือ var วิธีนี้ช่วยแก้ปัญหาอย่างหนึ่งในการใช้การแบ่งออกเป็นส่วนๆ กับการรับช่วง ซึ่งก่อนหน้านี้ต้องใช้พร็อพเพอร์ตี้ 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 คุณสามารถรายงานข้อบกพร่องได้